home *** CD-ROM | disk | FTP | other *** search
/ Mac-Source 1994 July / Mac-Source_July_1994.iso / Other Langs / Tickle-4.0 (tcl) / tcl / extend / man / TclX.man < prev    next >
Encoding:
Text File  |  1993-10-26  |  87.3 KB  |  2,388 lines  |  [TEXT/MPS ]
  1. .\"
  2. .\" TclX.man
  3. .\"
  4. .\" Extended Tcl binary file search command.
  5. .\"----------------------------------------------------------------------------
  6. .\" Copyright 1992-1993 Karl Lehenbauer and Mark Diekhans.
  7. .\"
  8. .\" Permission to use, copy, modify, and distribute this software and its
  9. .\" documentation for any purpose and without fee is hereby granted, provided
  10. .\" that the above copyright notice appear in all copies.  Karl Lehenbauer and
  11. .\" Mark Diekhans make no representations about the suitability of this
  12. .\" software for any purpose.  It is provided "as is" without express or
  13. .\" implied warranty.
  14. .\"----------------------------------------------------------------------------
  15. .\" $Id: TclX.man,v 2.27 1993/08/31 23:52:02 markd Exp $
  16. .\"----------------------------------------------------------------------------
  17. .\"
  18. .TH "TclX" TCL "" "Tcl"
  19. .ad b
  20. .SH NAME
  21. TclX - Extended Tcl: Extended command set for Tcl
  22. '
  23. .SH "INTRODUCTION"
  24. .PP
  25. This man page contains the documentation for all of the extensions that are
  26. added to Tcl 6.2 by Extended Tcl (TclX 6.2b).
  27. These extensions provide extend Tcl's
  28. capabilities by adding new commands to it, without changing the syntax of
  29. standard Tcl.  Extended Tcl is a superset of standard Tcl and is built
  30. alongside
  31. the standard Tcl sources.  Extended Tcl has three basic functional areas:
  32. A set of new commands, a Tcl shell (i.e. a Unix shell-style command line
  33. and interactive environment),  and a user-extensible library of useful
  34. Tcl procedures, any of which can be automatically loaded on the first
  35. attempt to execute it.
  36. .PP
  37. The command descriptions are separated into several sections:
  38. ???Redo this ???
  39. .RS 5
  40. .TP
  41. o General Commands
  42. .TP
  43. o Debugging and Development Commands
  44. .TP
  45. o Unix Access Commands
  46. .TP
  47. o File I/O Commands
  48. .TP
  49. o TCP/IP Server Access
  50. .TP
  51. o File Scanning Commands
  52. .TP
  53. o Math Commands
  54. .TP
  55. o List Maninipulation Commands
  56. .TP
  57. o Keyed Lists
  58. .TP
  59. o String and Character Manipulation Commands
  60. .TP
  61. o XPG/3 Message Catalog Commands
  62. .TP
  63. o Tcl Shell and Development Environment ???Funny name??
  64. .TP
  65. o Help Facility
  66. .TP
  67. o Tcl Shell Initialization Sequence ???Combine these sections.
  68. .TP
  69. o Tcl Initialization File
  70. .TP
  71. o Tcl Shell Variables
  72. .TP
  73. o Tcl Shell Procedures ??
  74. .TP
  75. o Tcl Loadable Libraries and Packages
  76. .RE
  77. '
  78. .SH "GENERAL COMMANDS"
  79. .PP
  80. A set of general, useful Tcl commands, includes a command to begin
  81. an interactive session with Tcl, a facility for tracing execution,
  82. and a looping command.
  83. '
  84. '@help: tcl/status/dirs
  85. '@brief: List the directories in the directory stack.
  86. .TP
  87. .B dirs
  88. This procedure lists the directories in the directory stack.
  89. '@endhelp
  90. '
  91. '@help: tcl/control/commandloop
  92. '@brief: Create an interactive command loop.
  93. .TP
  94. .B commandloop ?\fIprompt1\fR? ?\fIprompt2\fR?
  95. .br
  96. Create an interactive command loop for the current TCL interpreter.  This
  97. command receives commands from stdin and executes them.  It is
  98. useful TCL scripts that do not normally converse interactively with
  99. a user through a Tcl command interpreter, but which sometimes want
  100. to enter this mode.
  101. .sp
  102. \fIPrompt1\fR is a Tcl command string that is evaluated to determine
  103. the text of the prompt string.  The old value of \fBtcl_prompt1\fR is
  104. saved and it is set to this value for the duration of the command loop.
  105. \fIPrompt2\fR is a command string that is evaluated to determine
  106. the ``downlevel prompt'', which is
  107. the prompt which is issued for continuation input.  The old value of
  108. \fBtcl_prompt2\fR is
  109. saved and it is set to this value for the duration of the command loop.
  110. .sp
  111. When the command
  112. terminates, the variables for the prompt hooks will be set to their old value.
  113. If these arguments are not specified, the prompt hooks use their current
  114. value.  Prompt hooks are TCL code that return as their result the prompt to
  115. output.  The result of the last command executed in the command string (which
  116. may be a \fBreturn\fR) will be used as the prompt.
  117. '@endhelp
  118. '
  119. '@help: tcl/files/echo
  120. '@brief: Echo one or more strings to stdout, followed by a newline.
  121. .TP
  122. .B echo ?\fIstr ...\fR?
  123. .br
  124. Writes zero or more strings to standard output, followed by a newline.
  125. '@endhelp
  126. '
  127. '@help: tcl/status/infox
  128. '@brief: Return information about Extended Tcl, or the current application.
  129. .TP
  130. .B infox \fIoption\fR
  131. .br
  132. Return information about Extended Tcl, or the current application.  
  133. The following \fBinfox\fR command options are available:
  134. .RS 5
  135. .TP
  136. .B version
  137. Return the version number of Extended Tcl.  The version number for
  138. Extended Tcl is generated by combining the base version of the standard Tcl
  139. code with a letter indicating the version of Extended Tcl being used.  This is
  140. the documentation for version \fBtcl6.2b\fR.
  141. .TP
  142. .B patchlevel
  143. Return the patchlevel for Extended Tcl.
  144. .TP
  145. .B posix_signals
  146. Return \fB1\fR if Posix signals are available (\fBblock\fR and \fBunblock\fR
  147. options available for the signal command).  \fB0\fR is returned if Posix
  148. signals are not available.
  149. .TP
  150. .B appname
  151. Return the symbolic application name of the current application linked with
  152. the Extended Tcl library.  The C variable \fBtclAppName\fR must be set by the
  153. application to return an application specific value for this variable.
  154. .TP
  155. .B applongname
  156. Return a natural language name for the current application. The C variable
  157. \fBtclLongAppName\fR must be set by the application to return an application
  158. specific value for this variable.
  159. .TP
  160. .B appversion
  161. Return the version number for the current application.  The C variable
  162. \fBtclAppVersion\fR must be set by the application to return an 
  163. application-specific value for this variable.
  164. .RE
  165. '@endhelp
  166. '
  167. '@help: tcl/variables/for_array_keys
  168. '@brief: Do a foreach-style loop on each key in an array.
  169. .TP
  170. .B for_array_keys \fIvar array_name code\fR
  171. .br
  172. This procedure performs a foreach-style loop for each key in the named
  173. array.  The \fBbreak\fR and \fBcontinue\fR statements work as with
  174. \fBforeach\fR.
  175. '@endhelp
  176. '
  177. '@help: tcl/files/for_recursive_glob
  178. '@brief: Perform a foreach-style loop for all globbed files and directories.
  179. .TP
  180. .B for_recursive_glob \fIvar globlist code\fR
  181. .br
  182. This procedure performs a foreach-style loop for each file and directory
  183. that recursively matched one or more patterns specified in the call to
  184. \fBfor_recursive_glob\fR, setting \fIvar\fR to the matching file or
  185. directory, and calling \fIcode\fR.  The \fBbreak\fR and \fBcontinue\fR
  186. statements work as expected.  This procedure does not follow symbolic
  187. links.
  188. '@endhelp
  189. '
  190. '@help: tcl/control/loop
  191. '@brief: Higher-performance for-style loop.
  192. .TP
  193. .B loop \fIvar first limit ?increment? body\fR
  194. .br
  195. \fBLoop\fR is a looping command, similar in behavior to the Tcl \fBfor\fR
  196. statement, except that the \fBloop\fR statement achieves substantially higher
  197. performance and is easier to code when the beginning and ending values of a
  198. loop are known, and the loop variable is to be incremented by a known, fixed
  199. amount every time through the loop.
  200. .sp
  201.  The \fIvar\fR argument is the name of a Tcl variable that will contain the
  202. loop index.  The loop index is set to the value specified by
  203. \fIfirst\fR.  The Tcl interpreter is invoked upon \fIbody\fR zero or more
  204. times, where \fIvar\fR is incremented by \fIincrement\fR every time through
  205. the loop, or by one if \fIincrement\fR is not specified.  \fIIncrement\fR can
  206. be negative in which case the loop will count downwards.
  207. .sp
  208. When \fIvar\fR reaches \fIlimit\fR, the loop terminates without a subsequent
  209. execution of \fIbody\fR.  For instance, if the original \fBloop\fR parameters
  210. would cause \fBloop\fR to terminate, say \fIfirst\fR was one, \fIlimit\fR was
  211. zero and \fIincrement\fR was not specified or was non-negative, \fIbody\fR is
  212. not executed at all and \fBloop\fR returns.
  213. .sp
  214. The \fIfirst\fR, \fIlimit\fR and \fIincrement\fR are integer expressions.
  215. They are only evaulated once at the beginning of the loop.
  216. .sp
  217. If a \fBcontinue\fR command is invoked within \fIbody\fR then
  218. any remaining commands in the current execution of \fIbody\fR are skipped,
  219. as in the \fBfor\fR command.
  220. If a \fBbreak\fR command is invoked
  221. within \fIbody\fR
  222. then the \fBloop\fR command will
  223. return immediately.
  224. \fBLoop\fR returns an empty string.
  225. '@endhelp
  226. '
  227. '@help: tcl/status/popd
  228. '@brief: Pop a directory from a stack of directories and cd to it.
  229. .TP
  230. .B popd
  231. .br
  232. This procedure pops the top directory entry from the directory stack and
  233. make it the current directory.
  234. '@endhelp
  235. '
  236. '@help: tcl/status/pushd
  237. '@brief: Push a directory to a stack of directories.
  238. .TP
  239. .B pushd ?\fIdir\fR?
  240. .br
  241. This procedure pushs the current directory onto the directory stack and
  242. \fBcd\fR to the specified directory.  If the directory is not specified,
  243. then the current directory is pushed, but remains unchanged.
  244. '@endhelp
  245. '
  246. '@help: tcl/files/recursive_glob
  247. '@brief: Do filename globbing, recursively descending all matched directories.
  248. .TP
  249. .B recursive_glob \fIgloblist\fR
  250. .br
  251. This procedure does the same thing as glob, except that it recursively
  252. descends all the matched subdirectories, returning a list of all the
  253. files that matched all pattern in the list \fIgloblist\fR.  This
  254. procedure does not follow symbolic links.
  255. '@endhelp
  256. '
  257. '@help: tcl/status/showproc
  258. '@brief: List the definition of the named procedure.
  259. .TP
  260. .B showproc \fI?procname ...?\fR
  261. .br
  262. This procedure lists the definition of the named procedures.  Loading
  263. them if it is not already loaded.  If no procedure names are supplied,
  264. the definitions of all currently loaded procedures are returned.
  265. '@endhelp
  266. '
  267. .TP
  268. .SH "DEBUGGING AND DEVELOPMENT COMMANDS"
  269. This section contains information on commands and procdures that are
  270. useful for developing and debugging Tcl scripts.
  271.  
  272. '@help: tcl/debug/cmdtrace
  273. '@brief: Trace Tcl execution.
  274. .TP
  275. .B cmdtrace \fIlevel\fR|\fBon\fR ?\fBnoeval\fR? ?\fBnotruncate\fR? ?\fIprocs\fR? ?\fIfileid\fR?
  276. .br
  277. Print a trace statement for all commands executed at depth of \fIlevel\fR or
  278. below (1 is the top level).  If \fBon\fR is specified, all commands at any
  279. level are traced.  The following options are available:
  280. .RS 5
  281. .TP
  282. .B noeval
  283. Causes arguments to be printed unevaluated.  If \fBnoeval\fR
  284. is specified, the arguments are printed before
  285. evaluation.  Otherwise, they are printed afterwards.
  286. .sp
  287.  If the command line is longer than 60 characters, it is truncated
  288. to 60 and a "..." is postpended to indicate that there was more output
  289. than was displayed.
  290. If an evaluated 
  291. argument contains a space, the entire argument will be enclosed inside of
  292. braces (`{}') to allow the reader to visually separate the arguments from
  293. each other.
  294. .TP
  295. .B notruncate
  296. Disables the truncation of commands and evaluated arguments.
  297. .TP
  298. .B procs
  299. Enables the tracing of procedure calls only.  Commands that aren't
  300. procedure calls (i.e. calls to commands that are written in C, C++
  301. or some object-compatible language) are not traced if the \fBprocs\fR
  302. option is specified.  This option is particularly useful for greatly
  303. reducing the output of \fBcmdtrace\fR while debugging.
  304. .TP
  305. .B fileid
  306. This is a file id as returned by the \fBopen\fR command.  If specified, then
  307. the trace output will be written to the file rather than stdout.  A stdio
  308. buffer flush is done after every line is written so that the trace may be
  309. monitored externally or provide useful information for debugging problems that
  310. cause core dumps.
  311. .RE
  312. .TP
  313. .B cmdtrace off
  314. Turn off all tracing.
  315. .TP
  316. .B cmdtrace depth
  317. .br
  318. Returns the current maximum trace level, or zero if trace is disabled.
  319. '@endhelp
  320. '
  321. '@help: tcl/debug/edprocs
  322. '@brief: Edit named procs, or all procs.
  323. .TP
  324. .B edprocs ?\fIproc\fR...?
  325. .br
  326. This procedure writes the named procedures, or all currently defined
  327. procedures, to a temporary file, then calls an editor on it (as
  328. specified by the \fBEDITOR\fR environment variable, or \fBvi\fR if none
  329. is specified), then sources the file back in if it was changed.
  330. '@endhelp
  331. '
  332. '@help: tcl/debug/profile
  333. '@brief: Collect Tcl script performance profile data.
  334. .TP
  335. .B profile ?-commands? on
  336. .B profile off \fIarrayVar\fR
  337. .br
  338. This command is used to collect a performance profile of a Tcl script.  It
  339. collects data at the Tcl procedure level. The number of calls to a procedure,
  340. and the amount of real and CPU time is collected. Time is also collected for
  341. the global context.  The procedure data is collected by bucketing it based on
  342. the procedure call stack, this allows determination of how much time is spent
  343. in a particular procedure in each of it's calling contexts.
  344. .sp
  345. The \fBon\fR option enables profile data collection. If the \fB-commands\fR
  346. option is specifed, data on all commands within a procedure is collected
  347. as well a procedures.  Multiple occurrences of a command within a procedure
  348. are not distinguished, but this data may still be useful for analysis.
  349. .sp
  350. The \fBoff\fR option turns off profiling and moves the data collected to the
  351. array \fIarrayVar\fR.  The array is address by a list containing the procedure
  352. call stack.  Element zero is the top of the stack, the procedure that the
  353. data is for.  The data in each entry is a list consisting of the procedure
  354. call count and the real time and CPU time in milliseconds spent in the
  355. procedure (and all procedures it called). The list is in the form {\fIcount
  356. real cpu\fR}.
  357. A Tcl procedure \fBprofrep\fR is supplied for reducing the data and
  358. producing a report
  359. '@endhelp
  360. '
  361. '@help: tcl/debug/profrep
  362. '@brief: Generate a report from data collect from the profile command.
  363. .TP
  364. .B profrep \fIprofDataVar sortKey stackDepth\fR ?\fIoutFile\fR? ?\fIuserTitle\fR?
  365. .br
  366. This procedure generates a report from data collect from the profile command.
  367. \fBProfDataVar\fR is the name of the array containing the data returned by the
  368. \fBprofile\fR command. \fBSortKey\fR indicates which data value to sort by.
  369. It should be one of "\fBcalls\fR", "\fBcpu\fR" or "\fBreal\fR".
  370. \fBStackDepth\fR is the stack depth to consider significant.  A value of 1
  371. reports by procedure only, a value of 2 reports by procedure and its caller,
  372. etc. \fBOutFile\fR is the name of file to write the report to.  If omitted,
  373. stdout is assumed.  \fBUserTitle\fR is an optional title line to add to
  374. output.
  375. '@endhelp
  376. '
  377. '@help: tcl/debug/saveprocs
  378. '@brief: Save named procs to a file, or all procs.
  379. .TP
  380. .B saveprocs \fIfileName\fR ?\fIproc\fR...?
  381. .br
  382. This prodcure saves the definition of the named procedure, or all
  383. currently defined procedures if none is specified, to the named file.
  384. '@endhelp
  385. '
  386. .SH "UNIX ACCESS COMMANDS
  387. .PP
  388. These commands provide access to many basic Unix facilities, including process
  389. handling, date and time processing, signal handling,
  390. linking and unlinking files,
  391. setting file, process, and user attributes, and the executing
  392. commands via the shell.
  393. '
  394. '@help: tcl/time/alarm
  395. '@brief: Set a process alarm clock.
  396. .TP
  397. .B alarm \fIseconds\fR
  398. .br
  399. Instructs the system to send a SIGALRM signal in the specified number of
  400. seconds.  This is a floating point number, so fractions of a section may be
  401. specified.
  402. If \fIseconds\fR is 0.0, any previous alarm request is canceled.
  403. Only one alarm at a time may be active; the command returns the number of
  404. seconds left in the previous alarm.  On systems without the \fBsetitimer\fR
  405. system call, \fIseconds\fR is rounded up to an even number of seconds.
  406. '@endhelp
  407. '
  408. '@help: tcl/files/chgrp
  409. '@brief: Change file group.
  410. .TP
  411. .B chgrp \fIgroup\fR \fIfilelist\fR
  412. .br
  413. Set the
  414. group id of each file in the list \fIfilelist\fR to \fIgroup\fR, which can
  415. be either a
  416. group name or a numeric group id.
  417. '@endhelp
  418. '
  419. '@help: tcl/files/chmod
  420. '@brief: Set file permissions.
  421. .TP
  422. .B chmod \fImode\fR \fIfilelist\fR
  423. .br
  424. Set permissions of each of the files in the list \fIfilelist\fR to \fImode\fR,
  425. where \fImode\fR is an absolute numeric mode or symbolic permissions as in the
  426. UNIX \fBchmod(1)\fR command.  To specify a mode as octal, it should be
  427. prefixed with a "0" (e.g. 0622).
  428. '@endhelp
  429. '
  430. '@help: tcl/files/chown
  431. '@brief: Change file owner and/or group.
  432. .TP
  433. .B chown \fIowner\fR|{\fIowner group\fR} \fIfilelist\fR
  434. .br
  435. Set owner of each file in the list \fIfilelist\fR to \fIowner\fR, which can
  436. be a user
  437. name or numeric user id.  If the first parameter is a list, then the
  438. owner is set to the first element of the list and the group is set to the
  439. second element.  \fIGroup\fR can be a group name or numeric group id.
  440. If \fIgroup\fR is {}, then the file group will be set to the login
  441. group of the specified user.
  442. '@endhelp
  443. '
  444. '@help: tcl/time/convertclock
  445. '@brief: Parse and convert a date and time string to integer clock value.
  446. .TP
  447. .B convertclock \fIdateString\fR ?\fBGMT\fR|{}? ?\fIbaseClock\fR?
  448. .br
  449. Convert \fIdateString\fR to an integer clock value (see \fBgetclock\fR).
  450. This command can parse and convert virtually any standard date and/or time
  451. string, which can include standard time zone mnemonics.  If only a time is
  452. specified, the current date is assumed.  If the string does not contain a
  453. time zone mnemonic, the local time zone is assumed, unless the \fBGMT\fR 
  454. argument is specified, in which case the clock value is calculated assuming
  455. that the specified time is relative to Greenwich Mean Time.
  456. If \fIbaseClock\fR is specified,
  457. it is taken as the current clock value.  This is useful for determining the
  458. time on a specific day.
  459. .sp
  460. The character string consists of zero or more specifications of the following
  461. form:
  462. .sp
  463. .I time
  464. - A time of day, which is of the form
  465. .IR hh [ :mm [ :ss ]]
  466. .RI [ meridian ]
  467. .RI [ zone ]
  468. or
  469. .IR hhmm
  470. .RI [ meridian ]
  471. .RI [ zone ].
  472. If no meridian is specified,
  473. .I hh
  474. is interpreted on a 24-hour clock.
  475. .sp
  476. .I date
  477. - A specific month and day with optional year.
  478. The acceptable formats are
  479. .IR mm/dd [ /yy ],
  480. .IR yyyy/mm/dd ,
  481. .IR "monthname dd" "[, " yy ],
  482. .IR "dd monthname" " [" yy "],
  483. and
  484. .IR "day, dd monthname yy" .
  485. The default year is the current year.
  486. If the year is less then 100, then 1900 is added to it.
  487. .sp
  488. .I "relative time"
  489. - A specification relative to the current time.
  490. The format is
  491. .IR "number unit" ;
  492. acceptable units are
  493. .IR year ,
  494. .IR fortnight ,
  495. .IR month ,
  496. .IR week ,
  497. .IR day ,
  498. .IR hour ,
  499. .I minute
  500. (or
  501. .IR min ),
  502. and
  503. .I second
  504. (or
  505. .IR sec ).
  506. The unit can be specified as a singular or plural, as in
  507. .IR "3 weeks" .
  508. These modifiers may also be specified:
  509. .IR  tomorrow ,
  510. .IR  yesterday ,
  511. .IR  today ,
  512. .IR  now ,
  513. .IR  last ,
  514. .IR  this ,
  515. .IR  next ,
  516. .IR  ago.
  517. .sp
  518. The actual date is calculated according to the following steps.
  519. First, any absolute date and/or time is processed and converted.
  520. Using that time as the base, day-of-week specifications are added.
  521. Next, relative specifications are used.
  522. If a date or day is specified, and no absolute or relative time is given,
  523. midnight is used.
  524. Finally, a correction is applied so that the correct hour of the day is
  525. produced after allowing for daylight savings time differences.
  526. .sp
  527. .I convertclock
  528. ignores case when parsing all words.
  529. The names of the months and days of the week can be abbreviated to their
  530. first three letters, with optional trailing period.
  531. Periods are ignored in any timezone or meridian values.
  532. The only dates in the range 1902 and 2037 may be
  533. converted. 
  534. Some examples are:
  535. .sp
  536. .nf
  537. .ft CW
  538.     convertclock "14 Feb 92"
  539.     convertclock "Feb 14, 1992 12:20 PM PST"
  540.     convertclock "12:20 PM Feb 14, 1992"
  541. .ft R
  542. .fi
  543. '@endhelp
  544. '
  545. '@help: tcl/processes/execl
  546. '@brief: Perform a process exec, executing a file.
  547. .TP
  548. .B execl \fIprog\fR ?\fIarglist\fR?
  549. .br
  550. Do an execl, replacing the current program (either Extended Tcl or an
  551. application with Extended Tcl embedded into it) with \fIprog\fR and
  552. passing the arguments in the list \fIarglist\fR.
  553. '@endhelp
  554. '
  555. '@help: tcl/time/fmtclock
  556. '@brief: Convert an integer time value to human-readable format.
  557. .TP
  558. .B fmtclock \fIclockval\fR ?\fIformat\fR? ?\fBGMT|{}\fR?
  559. .br
  560. Converts a Unix integer time value, typically returned by
  561. \fBgetclock\fR, \fBconvertclock\fR, or the \fBatime\fR, \fBmtime\fR,
  562. or \fBctime\fR options of the \fBfile\fR command, to human-readable
  563. form.  The \fIformat\fR argument is a string that describes how the
  564. date and time are to be formatted.
  565. Field descriptors consist of a ``%'' followed by a field
  566. descriptor character.  All other characters are copied into the result.
  567. Valid field descriptors are:
  568. .sp
  569. .nf
  570. .ft CW
  571.     %% - Insert a %.
  572.     %a - Abbreviated weekday name.
  573.     %A - Full weekday name
  574.     %b - Abbreviated month name.
  575.     %B - Full month name.
  576.     %d - Day of month (01 - 31).
  577.     %D - Date as %m/%d/%y.
  578.     %e - Day of month (1-31), no leading zeros.
  579.     %h - Abbreviated month name.
  580.     %H - Hour (00 - 23).
  581.     %I - Hour (00 - 12).
  582.     %j - Day number of year (001 - 366).
  583.     %m - Month number (01 - 12).
  584.     %M - Minute (00 - 59).
  585.     %n - Insert a new line.
  586.     %p - AM or PM.
  587.     %r - Time as %I:%M:%S %p.
  588.     %R - Time as %H:%M.
  589.     %S - Seconds (00 - 59).
  590.     %t - Insert a tab.
  591.     %T - Time as %H:%M:%S.
  592.     %U - Week number of year (01 - 52), Sunday is the first 
  593.          day of the week.
  594.     %w - Weekday number (Sunday = 0).
  595.     %W - Week number of year (01 - 52), Monday is the first 
  596.          day of the week.
  597.     %x - Local specific date format.
  598.     %X - Local specific time format.
  599.     %y - Year within century (00 - 99).
  600.     %Y - Year as ccyy (e.g. 1990)
  601.     %Z - Time zone name.
  602. .fi
  603. .ft R
  604. .sp
  605. If format is not specified, "%a %b %d %H:%M:%S %Z %Y" is used.  If \fBGMT\fR
  606. is specified, the time will be formated as Greenwich Mean Time. If the
  607. argument is not specified or is empty, then the local timezone will be used as
  608. defined by the TIMEZONE environment variable.
  609. '@endhelp
  610. '
  611. '@help: tcl/processes/fork
  612. '@brief: Fork the current Tcl process.
  613. .TP
  614. .B fork
  615. .br
  616. Fork the current Tcl process.  Fork returns zero to the child process and the
  617. process number of the child to the parent process. 
  618. If the fork fails, a Tcl error is generated.
  619. .sp
  620. If an \fBexecl\fR is not
  621. going to be performed before the child process does output, or if a
  622. \fBclose\fR and \fBdup\fR sequence is going to be performed on \fBstdout\fR or
  623. \fBstderr\fR, then a
  624. \fBflush\fR should be issued against \fBstdout\fR, \fBstderr\fR and any other
  625. open output file before doing the \fBfork\fR. Otherwise characters from the
  626. parent process pending in the buffers will be output by both the parent
  627. and child processes.
  628. '@endhelp
  629. '
  630. '@help: tcl/time/getclock
  631. '@brief: Return current date and time as an integer value.
  632. .TP
  633. .B getclock
  634. .br
  635. Return the current date and time as a system-dependent integer value.  The
  636. unit of the value is seconds, allowing it to be used for relative time
  637. calculations.
  638. '@endhelp
  639. '
  640. '@help: tcl/status/id
  641. '@brief: Access, set or convert process, user and group information.
  642. .TP
  643. .B id options
  644. .br
  645. This command provides a means of getting, setting and converting user, group
  646. and process ids.  The \fBid\fR command has the following options:
  647. '
  648. .RS 5
  649. .TP
  650. .B id user \fR?\fIname\fR?
  651. .TP
  652. .B id userid \fR?\fIuid\fR?
  653. Set the real and effective user ID to \fIname\fR or \fIuid\fR, if the
  654. name (or uid) is valid and permissions allow it.  If the name (or uid)
  655. is not specified, the current name (or uid) is returned.
  656. .TP
  657. .B id convert userid \fIuid\fR
  658. .TP
  659. .B id convert user \fIname\fR
  660. Convert a user ID number to a user name, or vice versa.
  661. .TP
  662. .B id group \fR?\fIname\fR?
  663. .TP
  664. .B id groupid \fR?\fIgid\fR?
  665. Set the real and effective group ID to \fIname\fR or \fIgid\fR, if the
  666. name (or gid) is valid and permissions allow it.  If the group name
  667. (or gid) is not specified, the current group name (or gid) is returned.
  668. .TP
  669. .B id convert groupid \fIgid\fR
  670. .TP
  671. .B id convert group \fIname\fR
  672. Convert a group ID number to a group name, or vice versa.
  673. .TP
  674. .B id effective user
  675. .TP
  676. .B id effective userid
  677. Return the effective user name, or effective user ID number, respectively.
  678. .TP
  679. .B id effective group
  680. .TP
  681. .B id effective groupid
  682. Return the effective group name, or effective group ID number, respectively.
  683. .TP
  684. .B id process
  685. .br
  686. Return the process ID of the current process.
  687. .TP
  688. .B id process parent
  689. .br
  690. Return the process ID of the parent of the current process.
  691. .TP
  692. .B id process group
  693. .br
  694. Return the process group ID of the current process.
  695. .TP
  696. .B id process group set
  697. .br
  698. Set the process group ID of the current process to its process ID.
  699. .RE
  700. '@endhelp
  701. '
  702. '@help: tcl/processes/kill
  703. '@brief: Send a signal to the specified process.
  704. .TP
  705. .B kill ?\fIsignal\fR? \fIprocesslist\fR
  706. .br
  707. Send a signal to the each process in the list \fIprocesslist\fR, if permitted.
  708. \fISignal\fR, if present, is the signal number or the symbolic name of the
  709. signal, see the signal system call manual page.  The leading ``SIG''
  710. is optional
  711. when the signal is specified by its symbolic name.
  712. The default for \fIsigno\fR is 15, SIGTERM.
  713. '@endhelp
  714. '
  715. '@help: tcl/files/link
  716. '@brief: Create a link to a file.
  717. .TP
  718. .B link ?\fB-sym\fR? \fIsrcpath destpath\fR
  719. .br
  720. Create a directory entry, \fIdestpath\fR, linking it to the existing file,
  721. \fIsrcpath\fR.  If \fB-sym\fR is specified, a symbolic link, rather than
  722. a hard link, is created.  (The \fB-sym\fR option is only available
  723. on systems that support symbolic links.)
  724. '@endhelp
  725. '
  726. '@help: tcl/files/mkdir
  727. '@brief: Create a new directory
  728. .TP
  729. .B mkdir ?-path? \fIdirList\fR
  730. .br
  731. Create each of the directories in the list \fIdirList\fR.  The mode on the
  732. new directories is 777, modified by the umask.  If \fB-path\fR is specified,
  733. then any non-existent parent directories in the specified path(s) are also
  734. created.
  735. '@endhelp
  736. '
  737. '@help: tcl/files/rmdir
  738. '@brief: Remove directories
  739. .TP
  740. .B rmdir ?\fB-nocomplain\fR? \fIdirList\fR
  741. .br
  742. Remove each of the directories in the list \fIdirList\fR.
  743. If \fB-nocomplain\fR is specified, then errors will be ignored.
  744. '@endhelp
  745. '
  746. '@help: tcl/signals/signal
  747. '@brief: Specify action to take when a signal is received.
  748. .TP
  749. .B signal \fIaction\fR \fIsiglist\fR ?\fIcommand\fR?
  750. .br
  751. Specify the action to take when a Unix signal is received by Extended
  752. Tcl, or a program that embeds it.  \fISiglist\fR is a list
  753. of either the symbolic or numeric Unix signal (the SIG prefix is optional).
  754. \fIAction\fR is one of the following actions to be performed on receipt of the
  755. signal.
  756. .IP
  757. \fBdefault\fR - Perform system default action when signal is received
  758. (see \fBsignal\fR system call documentation).
  759. .IP
  760. \fBignore\fR - Ignore the signal.
  761. .IP
  762. \fBerror\fR - Generate a catchable Tcl error.  It will be as if the command
  763. that was running returned an error.  The error code will be in the form:
  764. .br
  765.     \fBPOSIX SIG\fR \fIsigname\fR
  766. .br
  767. For the death of child signal, \fIsigname\fR will always be SIGCHLD, rather
  768. than SIGCLD, to allow writing portable code.
  769. .IP
  770. \fBtrap\fR - When the signal occurs, execute \fIcommand\fR and continue
  771. execution if an error is not returned by \fIcommand\fR.  The command will
  772. be executed in the global context.  The command will be edited before
  773. execution, replacing occurrences of "%S" with the signal name.
  774. Occurrences of "%%" result in a single "%".  This editing occurs just before
  775. the trap command is evaluated. 
  776. If an error is returned,
  777. then follow the standard Tcl error mechanism.  Often \fIcommand\fR will just
  778. do an \fBexit\fR.
  779. .IP
  780. \fBget\fR - Retrieve the current settings of the specified signals.  A keyed
  781. list will be returned were the keys are one of the specified signals and the
  782. values are a list cosisting of the action associated with the signal, a
  783. \fB0\fR if the signal may be delivered (not block) and a \fB1\fR if it is
  784. blocked. The actions maybe one of `\fBdefault\fR',`\fBignore\fR',
  785. `\fBerror\fR' or `\fBtrap\fR.  If the action is trap, the third element is the
  786. command associated with the action.
  787. .IP
  788. \fBblock\fR - Block the specified signals from being received. (Posix systems
  789. only).
  790. .IP
  791. \fBunblock\fR - Allow the specified signal to be received. Pending signals
  792. will not occur. (Posix systems only).
  793. .sp
  794. The signal action will remain enabled after the specified signal has occurred.
  795. The exception to this is \fBSIGCHLD\fR on systems without Posix signals.
  796. For these systems, \fBSIGCHLD\fR is not be automatically reenabled.  After a
  797. \fBSIGCHLD\fR signal is received, a call to \fBwait\fR must be
  798. performed to retrieve the exit status of the child process before issuing
  799. another \fBsignal SIGCHLD \fI...\fR command.  For code that is to be portable
  800. between both types of systems, use this approach.
  801. .sp
  802. Signals are not processed until after the completion of the Tcl command that
  803. is executing when the signal is received.  If an interactive Tcl shell is
  804. running, then the \fBSIGINT\fR will be set to \fBerror\fR, non-interactive
  805. Tcl sessions leave \fBSIGINT\fR unchanged from when the process started
  806. (normally \fBdefault\fR for foreground processes and \fBignore\fR for
  807. processes in the background).
  808. '@endhelp
  809. '
  810. '@help: tcl/time/sleep
  811. '@brief: Sleep for the specified number of seconds.
  812. .TP
  813. .B sleep \fIseconds\fR
  814. .br
  815. Sleep the Extended Tcl process for \fIseconds\fR seconds.
  816. '@endhelp
  817. '
  818. '@help: tcl/processes/system
  819. '@brief: Execute command via `system' call.
  820. .TP
  821. .B system \fIcommand\fR
  822. .br
  823. Executes \fIcommand\fR via the \fIsystem\fR(3) call.  Differs from \fBexec\fR
  824. in that \fBsystem\fR doesn't return the executed command's standard output
  825. as the
  826. result string, and
  827. \fBsystem\fR goes through the Unix shell to provide wildcard
  828. expansion, redirection, etc,
  829. as is normal from an \fBsh\fR command line.  The exit code of
  830. the command is returned.
  831. '@endhelp
  832. '
  833. '@help: tcl/time/times
  834. '@brief: Get process and child execution times.
  835. .TP
  836. .B times
  837. .br
  838. Return a list containing the process and child execution times in the form:
  839. .br
  840.     \fIutime stime cutime cstime\fR
  841. .br
  842. Also see the \fItimes\fR(2) system call manual page.
  843. The values are in milliseconds.
  844. '@endhelp
  845. '
  846. '@help: tcl/status/umask
  847. '@brief: Get or set the file-creation mode mask.
  848. .TP
  849. .B umask ?\fIoctalmask\fR?
  850. .br
  851. Sets file-creation mode mask to the octal value of \fIoctalmask\fR.
  852. If \fIoctalmask\fR is omitted, the current mask is returned.
  853. '@endhelp
  854. '
  855. '@help: tcl/files/unlink
  856. '@brief: Delete (unlink) files.
  857. .TP
  858. .B unlink ?\fB-nocomplain\fR? \fIfilelist\fR
  859. .br
  860. Delete (unlink) the files whose names are in the list \fIfilelist\fR.
  861. If \fB-nocomplain\fR is specified, then errors will be ignored.
  862. '@endhelp
  863. '
  864. '@help: tcl/processes/wait
  865. '@brief: Wait for a child process to terminate.
  866. .TP
  867. .B wait \fR?\fB-nohang\fR? ?\fB-untraced\fR? ?\fB-pgroup\fR? ?\fIpid\fR?
  868. .br
  869. Waits for a process created with the \fBexecl\fR command to terminate, either
  870. due to an untrapped signal or call to \fIexit\fR system call.
  871. If the process id \fIpid\fR is specified, they wait on that process, otherwise
  872. wait on any child process to terminate.
  873. .sp
  874. If \fB-nohang\fR is specified, then don't block waiting on a process to
  875. terminate.  If no process is immediately available, return an empty list.
  876. If \fB-untraced\fR is specified then the status of child processes
  877. that are stopped, and whose status has not yet been reported since they
  878. stopped, are also returned.
  879. If \fB-pgroup\fR is specfied and \fIpid\fR is not specified, then wait
  880. on any child process whose process groupd ID is they same as the
  881. calling process. If \fIpid\fR is specified with \fB-pgroup\fR, then
  882. it is take as a process group ID, waiting on any process in that process group
  883. to terminate.
  884. .sp
  885. \fBWait\fR returns a list containing three elements: The first element is the
  886. process id of the process that terminated.
  887. If the process exited normally, the second element is `EXIT', and the third
  888. contains the numeric exit code.
  889. If the process terminated due to a signal, the second element is `SIG', and
  890. the third contains the signal name.
  891. If the process is currently stopped (on systems that support SIGSTP), the
  892. second element is `STOP', followed by the signal name.
  893. .sp
  894. Note that it is possible to wait on processes to terminate that were create
  895. in the background with the \fBexec\fR command.  However, if any other
  896. \fBexec\fR command is executed after the process terminates, then the
  897. process status will be reaped by the \fBexec\fR command and will not be
  898. available to the \fBwait\fR command.  
  899. '@endhelp
  900. '
  901. .SH "FILE I/O COMMANDS"
  902. .PP      
  903. These commands extend the stdio-style file I/O capabilities present in Tcl
  904. and above.
  905. These extensions include searching ASCII-sorted data files, copying files,
  906. duplicating file descriptors, control of file access options, retrieving open
  907. file status, and creating pipes with the \fBpipe\fR system call.  An interface
  908. to the \fBselect\fR system call is available on Unix systems that support
  909. it.
  910. .PP
  911. It should be noted that Tcl file I/O is implemented on top of the stdio 
  912. library.  By default, the file is buffered.  When communicating to a process
  913. through a pipe, a \fBflush\fR command should be issued to force the data
  914. out.  Alternatively, the \fBfcntl\fR command may be used to set the buffering
  915. mode of a file to line-buffered or unbuffered.
  916. '
  917. '@help: tcl/files/bsearch
  918. .TP
  919. .B bsearch \fIfileId key\fR ?\fIretvar\fR? ?\fIcompare_proc\fR?
  920. .br
  921. Search an opened file \fIfileId\fR containing lines of text sorted into
  922. ascending order for a match.
  923. \fIKey\fR contains the string to match.
  924. If \fIretvar\fR is specified, then the line from the
  925. file is returned in \fIretvar\fR, and the command returns \fB1\fR if \fIkey\fR
  926. was found, and \fB0\fR if it wasn't.  If \fIretvar\fR is not specified
  927. or is a null name, then the command returns the line that was found, or an
  928. empty string if \fIkey\fR wasn't found.
  929. .sp
  930. By default, the key is matched against the first white-space separated field
  931. in each line.  The field is treated as an ASCII string.  If \fIcompare_proc\fR
  932. is specified, then it
  933. defines the name of a Tcl procedure to evaluate against each
  934. line read from the sorted file during the execution of the
  935. \fBbsearch\fR command.  \fICompare_proc\fR takes two arguments, the key
  936. and a line extracted from the file.  The compare routine should return a
  937. number less than zero if the key is less than the line, zero if the key
  938. matches the line, or greater than zero if the key is greater than the line.
  939. The file must be sorted in ascending order according to the same criteria
  940. \fIcompare_proc\fR uses to compare the key with the line, or errouenous
  941. results will occur.
  942. '@endhelp
  943. '
  944. '@help: tcl/files/copyfile
  945. '@brief: Copy the remainder of one open file into another.
  946. .TP
  947. .B copyfile \fR?\fB-bytes \fInum\fR|\fB-maxbytes \fInum\fR? \fIfromFileId toFileId\fR
  948. .br
  949. Copies the rest of the file specified by \fIfromFileId\fR, starting
  950. from its current position,
  951. to the file specified by \fItoFileId\fR, starting from its current
  952. position.
  953. .sp
  954. If \fB-bytes\fR is specified, then \fBInum\fR bytes are copied.  If less than
  955. \fInum\fR bytes are available, an error is returned.  If \fB-maxbytes\fR is
  956. specified, then \fBInum\fR bytes are copied but no error is returned if less
  957. are available.
  958. .sp
  959. The command returns the number of bytes that were copied.
  960. .sp
  961. The \fB-bytes\fR option is particularly useful for mixing binary data
  962. in with ASCII commands or data in a data stream.
  963. '@endhelp
  964. '
  965. '@help: tcl/files/dup
  966. '@brief: Duplicate an open file
  967. .TP
  968. .B dup \fIfileId\fR ?\fItargetFileId\fR?
  969. .br
  970. Duplicate an open file.  A new file id is opened that addresses the
  971. same file as \fIfileId\fR.
  972. .sp
  973. If \fItargetFileId\fR is specified, the the file is dup to this specified file
  974. id.  Normally this is \fBstdin\fR, \fBstdout\fR, or \fBstderr\fR.
  975. The dup command will handle flushing output and closing this file.  It is
  976. recommended that the file not be closed in advanced if it is one of
  977. \fBstdin\fR, \fBstdout\fR, or \fBstderr\fR.  Otherwise internal C code that
  978. uses one of these files via direct access to stdio FILE struct may fail.
  979. .sp
  980. The procedure shown below will create a child process and
  981. set its standard input and output files to a pair
  982. of pipe files we pass as arguments.
  983. Finally the program does an \fBexecl\fR of a specified command,
  984. with the program's stdin and stdout coming from and going to
  985. our pair of pipes.
  986. .sp
  987. .nf
  988. .ft CW
  989.     proc ChildProcess {cmd inPipe outPipe} {
  990.         if {[set childPid [fork]] == 0} {
  991.             dup $inPipe stdin
  992.             close $inPipe
  993.             dup $outPipe stdout
  994.             close $outPipe
  995.  
  996.             execl $cmd
  997.             # will never make it here...
  998.         }
  999.         return $childPid
  1000.     }
  1001. .ft R
  1002. .fi
  1003. '@endhelp
  1004. '
  1005. '@help: tcl/files/fcntl
  1006. '@brief: Get or set file access options for an open file.
  1007. .TP
  1008. .B fcntl \fIfileId\fR \fIattribute ?value\fR? 
  1009. .br
  1010. This command either sets or clears a file option or returns its current
  1011. value.  If \fIvalue\fR are not specified, then the current value of
  1012. \fBattribute\fR is returned. The following attributes may be specified:
  1013. .IP
  1014. \fBRDONLY\fR - The file is opened for reading only. (Get only)
  1015. .sp
  1016. \fBWRONLY\fR - The file is opened for writing only.  (Get only)
  1017. .sp
  1018. \fBRDWR\fR - The file is opened for reading and writing.  (Get only)
  1019. .sp
  1020. \fBREAD\fR - If the file is readable. (Get only).
  1021. .sp
  1022. \fBWRITE\fR - If the file is writable. (Get only).
  1023. .sp
  1024. \fBAPPEND\fR - The file is opened for append-only writes.  All writes will
  1025. be forced to the end of the file.
  1026. .sp
  1027. \fBNONBLOCK\fR - The file is to be accessed with non-blocking I/O.  See the
  1028. \fBread\fR system call for a description of how it affects the behavior of
  1029. file reads.
  1030. .sp
  1031. \fBCLOEXEC\fR - Close the file on an process exec.  If the \fBexecl\fR
  1032. command or some other mechanism causes the process to do an
  1033. exec, the file will
  1034. be closed if this option is set.
  1035. .sp
  1036. \fBNOBUF\fR - The file is not buffered. If set, then there no stdio buffering
  1037. for the file.
  1038. .sp
  1039. \fBLINEBUF\fR - Output the file will be line buffered. The buffer will
  1040. be flushed when a newline is written, when the buffer is full,
  1041. or when input is requested.
  1042. .sp
  1043. The \fBAPPEND\fR, \fBNONBLOCK\fR, and \fBCLOEXEC\fR attributes may be set or
  1044. cleared by specifying the attribute name and a value \fB1\fR to set the
  1045. attribute and \fB0\fR to clear it.
  1046. .sp
  1047. The \fBNOBUF\fR and \fBLINEBUF\fR attributes may only be set (a value of
  1048. \fB1\fR) and only one of the options may be selected.
  1049. Once set, it may not be
  1050. changed.  These options should be set before any I/O operations have been done
  1051. on the file or data may be lost.
  1052. '@endhelp
  1053. '
  1054. '@help: tcl/files/flock
  1055. '@brief: Lock all or part of a file.
  1056. .TP
  1057. .B flock \fIoptions fileId\fR ?\fIstart\fR? ?\fIlength\fR? ?\fIorigin\fR?
  1058. .br
  1059. This command places a lock on all or part of the file specified by
  1060. \fIfileId\fR.  The lock is either advisory or mandatory, depending on the mode
  1061. bits of the file.  The lock is placed beginning at relative byte offset
  1062. \fIstart\fR for \fIlength\fR bytes.  If \fIstart\fR or \fIlength\fR is omitted
  1063. or empty, zero is assumed.  If \fIlength\fR is zero, then the lock always
  1064. extents to end of file, even if the file grows.  If \fIorigin\fR is
  1065. "\fBstart\fR", then the offset is relative to the beginning of the file. If it
  1066. is "\fBcurrent\fR", it is relative to the current access position in the file.
  1067. If it is "\fBend\fR", then it is relative to the end-of-file (a negative is
  1068. before the EOF, positive is after).  If \fIorigin\fR is omitted, \fBstart\fR
  1069. is assumed.
  1070. .sp
  1071. The following \fIoptions\fR are recognized:
  1072. .IP
  1073. \fB-read\fR - Place a read lock on the file.  Multiple processes may be
  1074. accessing the file with read-locks.
  1075. .IP
  1076. \fB-write\fR - Place a write lock on the file.  Only one process may be
  1077. accessing a file if there is a write lock.
  1078. .IP
  1079. \fB-nowait\fR - If specified, then the process will not block if the lock
  1080. can not be obtained.  With this option, the command returns 1 if the lock
  1081. is obtained and 0 if it is not.
  1082. .sp
  1083. See your system's \fBfcntl\fR system call documentation for full details of
  1084. the behavior of file locking.  If locking is being done on ranges of a
  1085. file, it is best to use unbuffered file access (see the \fBfcntl\fR command).
  1086. '@endhelp
  1087. '
  1088. '@help: tcl/files/for_file
  1089. '@brief: Do a foreach-style loop on each line in a file.
  1090. .TP
  1091. .B for_file \fIvar filename { code }\fR
  1092. .br
  1093. This procedure implements a loop over the contents of a file.
  1094. For each line in \fIfilename\fR, it sets
  1095. \fIvar\fR to the line and executes \fIcode\fR.
  1096. .sp
  1097. The \fBbreak\fR and \fBcontinue\fR commands work as with foreach.
  1098. .sp
  1099. For example, the command
  1100. .sp
  1101. .nf
  1102.     \fBfor_file line /etc/passwd {echo $line}\fR
  1103. .fi
  1104. .sp
  1105. would echo all the lines in the password file.
  1106. '@endhelp
  1107. '
  1108. '@help: tcl/files/funlock
  1109. '@brief: Remove a lock from part or all of a file.
  1110. .TP
  1111. .B funlock \fIfileId\fR ?\fIstart\fR? ?\fIlength\fR? ?\fIorigin\fR?
  1112. .br
  1113. Remove a locked from a file that was previously placed with the \fIflock\fR
  1114. command.  The arguments are the same as for the \fIflock\fR command, see
  1115. that command for more details.
  1116. '@endhelp
  1117. '
  1118. '@help: tcl/files/fstat
  1119. '@brief: Obtain status information about an open file.
  1120. .TP
  1121. .B fstat \fIfileId\fR ?\fIitem\fR?|?\fBstat \fIarrayvar\fR?
  1122. .br
  1123. Obtain status information about an open file.
  1124. .sp
  1125. The following keys are used to identify data items:
  1126. .br
  1127. .IP
  1128. o\ \fBatime\fR - The time of last access.
  1129. .IP
  1130. o\ \fBctime\fR - The time of last file status change
  1131. .IP
  1132. o\ \fBdev\fR - The device containing a directory for the file.  This value
  1133. uniquely identifies the file system that contains the file.
  1134. .IP
  1135. o\ \fBgid\fR - The group ID of the file's group.
  1136. .IP
  1137. o\ \fBino\fR - The inode number.  This field uniquely identifies the file in a
  1138. given file system.
  1139. .IP
  1140. o\ \fBmode\fR - The mode of the file (see the \fBmknod\fR system call).
  1141. .IP
  1142. o\ \fBmtime\fR - Time when the data in the file was last modified.
  1143. .IP
  1144. o\ \fBnlink\fR - The number of links to the file.
  1145. .IP
  1146. o\ \fBsize\fR - The file size in bytes.
  1147. .IP
  1148. o\ \fBtty\fR - If the file is associated with a terminal, then 1 otherwise 0.
  1149. .IP
  1150. o\ \fBtype\fR - The type of the file in symbolic form, which is one of the
  1151. following values: \fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR,
  1152. \fBblockSpecial\fR, \fBfifo\fR, \fBlink\fR, or \fBsocket\fR.
  1153. .IP
  1154. o\ \fBuid\fR - The user ID of the file's owner.
  1155. .sp
  1156. If one of these keys is specified as \fIitem\fR, then that data item is
  1157. returned.
  1158. .sp
  1159. If \fBstat \fIarrayvar\fR is specified, then the information is returned in
  1160. the array \fIarrrayvar\fR.  Each of the above keys indexes an element of the
  1161. array containing the data.
  1162. .sp
  1163. If only \fIfileId\fR is specified, the command returns the data as a keyed
  1164. list.
  1165. .sp
  1166. The following value may be returned only if explicitly asked for, it will not
  1167. be returned with the array or keyed list forms:
  1168. .IP
  1169. o\ \fBremotehost\fR - If \fIfileId\fR is a TCP/IP socket connection, then a
  1170. list is returned with the first element being the remote host IP address.  If
  1171. the remote host name can be found, it is returned as the second element of
  1172. the list.
  1173. '@endhelp
  1174. '
  1175. '@help: tcl/files/lgets
  1176. '@brief: Read a list for a file, handles embedded newlines.
  1177. .TP
  1178. .B lgets \fIfileId\fR ?\fIvarName\fR?
  1179. .br
  1180. Reads the next Tcl list from the file given by \fIfileId\fR and discards
  1181. the terminating newline character.  This command differs from the \fBgets\fR
  1182. command, in that it reads Tcl lists rather than lines.  If the list
  1183. contains a newline, then that newline will be returned as part of the result.
  1184. Only a newline not quoted as part of the list indicates the end of the list.
  1185. There is no corresponding command for outputing lists, as \fBputs\fR will
  1186. do this correctly.
  1187. If \fIvarName\fR is specified, then the line is placed in the variable
  1188. by that name and the return value is a count of the number of characters
  1189. read (not including the newline).
  1190. If the end of the file is reached before reading
  1191. any characters then \-1 is returned and \fIvarName\fR is set to an
  1192. empty string.
  1193. If \fIvarName\fR is not specified then the return value will be
  1194. the line (minus the newline character) or an empty string if
  1195. the end of the file is reached before reading any characters.
  1196. An empty string will also be returned if a line contains no characters
  1197. except the newline, so \fBeof\fR may have to be used to determine
  1198. what really happened.
  1199. '@endhelp
  1200. '
  1201. '@help: tcl/files/pipe
  1202. '@brief: Create a pipe.
  1203. .TP
  1204. .B pipe ?\fIfileId_var_r fileId_var_w\fR?
  1205. .br
  1206. Create a pipe.  If \fIfileId_var_r\fR
  1207. and \fIfileId_var_r\fR are specified, then \fBpipe\fR will set the a
  1208. variable named \fIfileId_var_r\fR to
  1209. contain the fileId of the side of the pipe that was opened for reading,
  1210. and \fIfileId_var_w\fR will contain the fileId of the side of the
  1211. pipe that was opened for writing.
  1212. .sp
  1213. If the fileId variables are not specified, then a
  1214. list containing the read and write fileIdw is returned as the
  1215. result of the command.
  1216. '@endhelp
  1217. '
  1218. '@help: tcl/files/read_file
  1219. '@brief: Read in a file to a string.
  1220. .TP
  1221. .B read_file ?\fB-nonewline\fR? \fIfileName\fR
  1222. .br
  1223. .B read_file \fIfileName\fR \fInumBytes\fR
  1224. .br
  1225. This proecure reads the file \fIfileName\fR and returns the contents as
  1226. a string.  If \fB-nonewline\fR is specified, then the last character of
  1227. the file is discarded if it is a newline.  The second form specifies
  1228. exactly how many bytes will be read and returned, unless there are fewer
  1229. than \fInumBytes\fR bytes left in the file; in this case, all the
  1230. remaining bytes are returned.
  1231. '@endhelp
  1232. '
  1233. '@help: tcl/files/select
  1234. '@brief: Synchronous I/O multiplexing.
  1235. .TP
  1236. .B select \fIreadfileIds\fR ?\fIwritefileIds\fR? ?\fIexceptfileIds\fR? ?\fItimeout\fR?
  1237. .br
  1238. This command allows an Extended Tcl program to wait
  1239. on zero or more files being ready for
  1240. for reading, writing, have an exceptional condition pending, or for
  1241. a timeout period to expire.
  1242. \fIreadFileIds\fR, \fIwriteFileIds\fR, \fIexceptFileIds\fR are each lists
  1243. of fileIds, as returned from \fBopen\fR, to query.  An empty list ({}) may
  1244. be specified if a category is not used. 
  1245. .sp
  1246. The files 
  1247. specified by
  1248. the \fIreadFileIds\fR list are checked to see if data is available for
  1249. reading. The \fIwriteFileIds\fR are checked if the specified
  1250. files are clear for writing.
  1251. The
  1252. \fIexceptFileIds\fR are checked to see if an exceptional condition has
  1253. occured (typically, an error).
  1254. The write and exception checking is most useful on devices, however,
  1255. the read checking is very useful when communicating with multiple
  1256. processes through pipes.  Select considers data pending in the stdio
  1257. input buffer for read files as being ready for reading, the files do.
  1258. not have to be unbuffered.
  1259. .sp
  1260. \fITimeout\fR is a floating point timeout value, in seconds.  If an empty
  1261. list is supplied (or the parameter is omitted), then no timeout is set.  If
  1262. the value is zero, then the \fBselect\fR command functions as a poll of the
  1263. files, returning immediately even if none are ready.
  1264. .sp
  1265. If the \fItimeout\fR period expires with none of the files becomming ready,
  1266. then the command returns an empty list.  Otherwise the command returns a 
  1267. list of three elements, each of those elements is a list of the fileIds
  1268. that are ready in the read, write and exception classes.  If none are ready in
  1269. a class, then that element will be the null list.  For example:
  1270. .sp
  1271. .nf
  1272.         select {file3 file4 file5} {file6 file7} {} 10.5
  1273.  
  1274. could return
  1275.  
  1276.         {file3 file4} {file6} {}
  1277.  
  1278. or perhaps
  1279.  
  1280.         file3 {} {}
  1281. .fi
  1282. .sp
  1283. '@endhelp
  1284. '
  1285. '@help: tcl/files/write_file
  1286. '@brief: Write strings out to a file.
  1287. .TP
  1288. .B write_file \fIfileName string ?string...?\fR
  1289. .br
  1290. This procedure writes the specified strings to the named file.
  1291. '@endhelp
  1292. '
  1293. .SH "TCP/IP SERVER ACCESS"
  1294. .PP
  1295. A command is provided to access TCP/IP based servers.  In addition it is
  1296. easy to build servers using Extended Tcl that run under \fBinetd\fR.  The
  1297. \fBfstat remotehost\fR request is useful for these servers.
  1298. '
  1299. '@help: tcl/files/server_open
  1300. '@brief: Open a connection to a TCP/IP server.
  1301. .TP
  1302. .B server_open ?\fIoption\fR? \fIhost service\fR
  1303. .br
  1304. Open a TCP/IP connection to a server of \fIhost\fR on the port specified by
  1305. \fIservice\fR.  The server is then accessed using the standard Tcl
  1306. file I/O commands.
  1307. \fIHost\fR may be a host name or an IP address.  \fIPort\fR
  1308. may be a port number of a service name.  Option is one of \fB-buf\fR or
  1309. \fR-nobuf\fR.  If no options is specified, \fB-buf\fR is the default.
  1310. .sp
  1311. If \fB-buf\fR is specified, then the file is buffered.
  1312. In this case, a pair of Tcl file ids are returned in a list.  The first id
  1313. is open for read access, the second for write.  When writing to the file,
  1314. the \fIflush\fR command must be used to force data in the buffer to
  1315. be sent to the server.  The \fIclose\fR command must be called against both
  1316. file ids when through with the socket.  Buffered access will result in 
  1317. significantly better performance when reading data and will also improve
  1318. a series of writes being done with out intermixed reads.  The \fIfcntl\fR
  1319. command may be used to make one of these files unbuffered.
  1320. .sp
  1321. if \fB-nobuf\fR is specified, then the file is unbuffered and a single file id,
  1322. open for both reading and writing, is returned.
  1323. '@endhelp
  1324. '
  1325. .SH "FILE SCANNING COMMANDS"
  1326. .PP
  1327. These commands provide a facility to scan files, matching lines of the file
  1328. against regular expressions and executing Tcl code on a match.  With this
  1329. facility you can use Tcl to do the sort of file processing
  1330. that is traditionally done with \fIawk\fR.  And since Tcl's approach is more
  1331. declarative, some of the scripts that can be rather
  1332. difficult to write in awk are simple to code in Tcl.
  1333. .PP
  1334. File scanning in Tcl centers around the concept of a \fIscan context\fR.
  1335. A scan context contains one or more match statements, which associate
  1336. regular expressions to scan for with Tcl code to be executed when the
  1337. expressions are matched.
  1338. '
  1339. '@help: tcl/filescan/scancontext
  1340. '@brief: Manage file scan contexts.
  1341. .TP
  1342. .B scancontext ?\fIoption\fR?
  1343. .br
  1344. This command manages file scan contexts.  A scan context is a collection of
  1345. regular expressions and commands to execute when that regular expression
  1346. matches a line of the file.  A context may also have a single default match,
  1347. to be applied against lines that do not match any of the regular expressions.
  1348. Multiple scan contexts may be defined and they may be reused on multiple files.
  1349. A scan context is identified by a context handle.  The \fBscancontext\fR
  1350. command takes
  1351. the following forms:
  1352. .TP
  1353. .B scancontext create
  1354. Create a new scan context.  The \fBscanmatch\fR command is used to define
  1355. patterns in the context.  A contexthandle is returned, which the Tcl
  1356. programmer uses to refer to the newly created scan context in calls
  1357. to the Tcl file scanning commands.
  1358. '
  1359. .TP
  1360. .B scancontext delete \fIcontexthandle\fR
  1361. .br
  1362. Delete the scan context identified by \fIcontexthandle\fR, and free all
  1363. of the
  1364. match statements and compiled regular expressions associated with the
  1365. specified context.
  1366. '@endhelp
  1367. '
  1368. '@help: tcl/filescan/scanfile
  1369. '@brief: Scan a file, executing match code when their patterns are matched.
  1370. .TP
  1371. .B scanfile \fIcontexthandle\fR \fIfileId\fR
  1372. .br
  1373. Scan the file specified by \fIfileId\fR, starting at the
  1374. current file position.  Check all patterns in the scan context specified by
  1375. \fIcontexthandle\fR against
  1376. it, executing the match commands corresponding to patterns matched.
  1377. '@endhelp
  1378. '@help: tcl/filescan/scanmatch
  1379. '@brief: Specify tcl code to execute when scanfile pattern is matched.
  1380. .TP
  1381. .B scanmatch ?\fB-nocase\fR? \fIcontexthandle\fR ?\fIregexp\fR? \fIcommands\fR
  1382. .br
  1383. Specify Tcl \fIcommands\fR, to be evaluated when \fIregexp\fR is matched by a
  1384. \fBscanfile\fR command.  The match is added to the scan context specified by
  1385. \fIcontexthandle\fR.  Any number of match statements may be
  1386. specified for a give context.  \fIRegexp\fR is a regular expression (see the
  1387. \fBregexp\fR command).  If \fB-nocase\fR is specified as the first argument,
  1388. the pattern is matched regardless of
  1389. alphabetic case.
  1390. .sp
  1391. If \fIregexp\fR is not specified, then a default match is
  1392. specified for the scan context.  The default match will be executed when a
  1393. line of the file does not match any of the regular expressions
  1394. in the current scancontext.
  1395. .sp
  1396. The array \fBmatchInfo\fR is available to the Tcl code that is executed
  1397. when an expression matches (or defaults).  It contans information about
  1398. the file being scanned and where within it the expression was matched.
  1399. .sp
  1400. \fBmatchInfo\fR is local to the top
  1401. level of the match command unless declared global at that level
  1402. by the Tcl \fBglobal\fR command.  If it is to
  1403. be used as a global, it \fImust\fR be declared global before \fBscanfile\fR is
  1404. called (since \fBscanfile\fR sets the \fBmatchInfo\fR before the match code is
  1405. executed, a subsequent \fBglobal\fR will override the local variable).
  1406. The following array entries are available:
  1407. .RS 5
  1408. .TP
  1409. .B matchInfo(line)
  1410. Contains the text of the line of the file that was matched.
  1411. .TP
  1412. .B matchInfo(offset)
  1413. The byte offset into the file of the first character of
  1414. the line that was matched.
  1415. .TP
  1416. .B matchInfo(linenum)
  1417. The line number of the line that was matched. This is relative to the first
  1418. line scanned, which is usually, but not necessarily, the first line of the
  1419. file.  The first line is line number one.
  1420. .TP
  1421. .B matchInfo(handle)
  1422. The file id (handle) of the file currently being scanned.
  1423. .TP
  1424. .B matchInfo(submatch0)
  1425. Will contain the characters matching the first parenthesized subexpression.
  1426. The second will be contained in \fBsubmatch1\fR, etc.
  1427. .TP
  1428. .B matchInfo(subindex0)
  1429. Will contain the a list of the starting and ending indices of the string
  1430. matching the first parenthesized subexpression.
  1431. The second will be contained in \fBsubindex1\fR, etc.
  1432. .RE
  1433. .PP
  1434. All \fBscanmatch\fR patterns that match a line will be processed in the order
  1435. in which their
  1436. specifications were added to the scan context.  The remainder of the
  1437. \fBscanmatch\fR pattern-command pairs may be skipped for a file line if a
  1438. \fBcontinue\fR is executed by the Tcl code of a preceding, matched
  1439. pattern.
  1440. .sp
  1441. If a \fBreturn\fR is
  1442. executed in the body of the match command, the \fBscanfile\fR command
  1443. currently in
  1444. progress returns, with the value passed to \fBreturn\fR as its
  1445. return value.
  1446. '@endhelp
  1447. '
  1448. .SH "MATH COMMANDS"
  1449. .PP
  1450. Several extended math commands commands make many additional math
  1451. functions available in TclX.  In addition, a set of procedures provide
  1452. command access to the math functions supported by the \fBexpr\fR command.
  1453.  
  1454. '@help: tcl/math/fmathcmds
  1455. '@brief: Command interfaces to the expr math functions (sin, cos, tan, etc).
  1456. .PP
  1457. The following procedures provide command interfaces to the expr math
  1458. functions. They take the same arguments as the \fBexpr\fR functions and
  1459. may take expressions as arguments.
  1460. .sp
  1461. .RS
  1462. .nf
  1463. .ta 3c 6c 9c
  1464. \fBabs\fR    \fBacos\fR    \fBasin\fR    \fBatan2\fR    
  1465. \fBatan\fR    \fBceil\fR    \fBcos\fR    \fBcosh\fR    
  1466. \fBdouble\fR    \fBexp\fR    \fBfloor\fR    \fBfmod\fR    
  1467. \fBhypot\fR    \fBint\fR    \fBlog10\fR    \fBlog\fR    
  1468. \fBpow\fR    \fBround\fR    \fBsin\fR    \fBsinh\fR    
  1469. \fBsqrt\fR    \fBtan\fR    \fBtanh\fR    
  1470. .fi
  1471. .RE
  1472. '@endhelp
  1473. '
  1474. '@help: tcl/math/max
  1475. '@brief: Return the argument that has the highest numeric value.
  1476. .TP
  1477. .B max \fInum1 num2\fR ?..\fInumN\fR?
  1478. .br
  1479. Returns the argument that has the highest numeric value. The arguments,
  1480. \fInumN\fR may be any interger or floating point values.
  1481. '@endhelp
  1482. '
  1483. '@help: tcl/math/min
  1484. '@brief: Return the argument that has the lowest numeric value.
  1485. .TP
  1486. .B min \fInum1 num2\fR ?..\fInumN\fR?
  1487. .br
  1488. Returns the argument that has the lowest numeric value. The arguments,
  1489. \fInumN\fR may be any interger or floating point values.
  1490. '@endhelp
  1491. '
  1492. '@help: tcl/math/random
  1493. '@brief: Return a pseudorandom integer or set the seed.
  1494. .TP
  1495. .B random \fBlimit\fR | \fBseed\fR ?\fIseedval\fR?
  1496. .br
  1497. Generate a pseudorandom integer number greater than or equal to zero and
  1498. less than \fIlimit\fR.  If \fBseed\fR is specified, then the command
  1499. resets the random number generator to a starting point derived from 
  1500. the \fBseedval\fR. This allows one to reproduce 
  1501. pseudorandom number sequences
  1502. for testing purposes.
  1503. If \fIseedval\fR is omitted, then the seed is set to a value based on current
  1504. system state and the current time, providing a reasonably interesting and
  1505. ever-changing seed.
  1506. '@endhelp
  1507. '
  1508. .SH "LIST MANINIPULATION COMMANDS"
  1509. .PP
  1510. Extended Tcl provides additional list manipulation commands and procedures.
  1511. '
  1512. '@help: tcl/lists/intersect
  1513. '@brief: Return a list containing every element present in both lists.
  1514. .TP
  1515. .B intersect \fIlista listb\fR
  1516. .br
  1517. Return the logical intersection of two lists.  The returned list will be
  1518. sorted.
  1519. .sp
  1520. (Note: This command is implemented as a procedure)
  1521. '@endhelp
  1522. '
  1523. '@help: tcl/lists/intersect3
  1524. '@brief: Return three lists from an intersection of two lists.
  1525. .TP
  1526. .B intersect3 \fIlista listb\fR
  1527. .br
  1528. This procedure intersects two lists, returning a list containing
  1529. three lists:  The first list returned is everything in \fIlista\fR
  1530. that wasn't in \fIlistb\fR.  The second list contains the intersection
  1531. of the two lists, and the third list contains all the elements that
  1532. were in \fIlistb\fR but weren't in \fIlista\fR.  The returned lists will be
  1533. sorted.
  1534. '@endhelp
  1535. '
  1536. '@help: tcl/lists/lassign
  1537. '@brief: Assign successive elements of a list to specified variables.
  1538. .TP
  1539. .B lassign \fIlist var\fR ?\fIvar\fR...?
  1540. .br
  1541. Assign successive elements of a list to specified variables.
  1542. Any leftover fields are discarded.  When there are more variable
  1543. names than fields, the remaining variables are set to the
  1544. empty string.
  1545. .sp
  1546. For example,
  1547. .sp
  1548. .nf
  1549.    lassign {dave 100 200 {Dave Foo}} name uid gid longName
  1550. .fi
  1551. .sp
  1552. Assigns \fIname\fR to ``dave'', \fIuid\fR to ``100'', \fIgid\fR to ``200'',
  1553. and \fIlongName\fR to ``Dave Foo''.
  1554. '@endhelp
  1555. '
  1556. '@help: tcl/lists/lempty
  1557. '@brief: Determine if a list is empty. 
  1558. .TP
  1559. .B lempty \fIlist\fR
  1560. .br
  1561. Determine if the specified list is empty.
  1562. If empty, 1 is returned, otherwise, 0 is returned.  This command is an
  1563. alternative to comparing a list to an empty string.
  1564. '@endhelp
  1565. '
  1566. '@help: tcl/lists/lrmdups
  1567. '@brief: Given a list, remove all of the duplicated elements.
  1568. .TP
  1569. .B lrmdups \fIlist\fR
  1570. .br
  1571. This procedure remove duplicate elements from a list.  The returned list
  1572. will be sorted.
  1573. '@endhelp
  1574. '
  1575. '@help: tcl/lists/lvarcat
  1576. '@brief: Concatenate the contents lists or strings into a variable
  1577. .TP
  1578. \fBlvarcat\fI var string ?\fR\fIstring...\fR?
  1579. .br
  1580. This command treats each \fIstring\fR argument as a list and concatenates them
  1581. to the end of the contents of \fIvar\fR, forming a a single list.  The list is
  1582. stored back into \fIvar\fR and also returned as the result.  if \fIvar\fR does
  1583. not exist, it is created.
  1584. '@endhelp
  1585. '
  1586. '@help: tcl/lists/lvarpop
  1587. '@brief: Pop or replace the specified element from a list.
  1588. .TP
  1589. .B lvarpop \fIvar\fR ?\fIindex\fR? ?\fIstring\fR?
  1590. .br
  1591. The \fBlvarpop\fR command pops (deletes) the element indexed by
  1592. \fIindex\fR from the list contained in the variable \fIvar\fR.
  1593. If \fIindex\fR is omitted, then 0 is assumed.
  1594. If \fIstring\fR, is specified, then the deleted element is replaced by 
  1595. \fIstring\fR. The replaced or deleted element is returned.
  1596. Thus ``lvarpop argv 0'' returns the first element of argv, setting
  1597. argv to contain the remainder of the string.
  1598. '@endhelp
  1599. '
  1600. '@help: tcl/lists/lvarpush
  1601. '@brief: Push or insert the an element into a list.
  1602. .TP
  1603. .B lvarpush \fIvar string\fR ?\fIindex\fR?
  1604. .br
  1605. The \fBlvarpush\fR command pushes (inserts) \fIstring\fR as an element in the
  1606. list contained in the variable \fIvar\fR.  The element is inserted before
  1607. position \fIindex\fR in the list. If \fIindex\fR is omitted, then 0 is
  1608. assumed.  If \fIvar\fR does not exists, it is created.
  1609. '@endhelp
  1610. '
  1611. '@help: tcl/lists/union
  1612. '@brief: Return the logical union of two lists.
  1613. .TP
  1614. .B union \fIlista listb\fR
  1615. This procedure returns the logical union of the two specified lists.
  1616. Any duplicate elements are removed.
  1617. '@endhelp
  1618. '
  1619. '@help: tcl/intro/keyedlists
  1620. '@brief: Introduction to keyed lists
  1621. .SH "KEYED LISTS"
  1622. .PP
  1623. Extended Tcl defines a special type of list referred to as \fIkeyed lists\fR.
  1624. These lists provided a structured data type built upon standard Tcl lists.
  1625. This provides a functionality similar to \fIstruct\fRs in the C 
  1626. programming language.
  1627. .sp
  1628. A keyed list is a list in which each element contains a key and value pair.
  1629. These element pairs are stored as lists themselves, where the key is the first
  1630. element of the list, and the value is the second.  The key-value pairs are
  1631. refered to as \fIfields\fR.
  1632. This is an example of a keyed list:
  1633. .IP
  1634.     {{NAME {Frank Zappa}} {JOB {musician and composer}}}
  1635. '
  1636. .PP
  1637. If the variable \fBperson\fR contained the above list, then
  1638. \fBkeylget person NAME\fR would return \fB{Frank Zappa}\fR.
  1639. Executing the command:
  1640. .IP
  1641. \fBkeylset person ID 106\fR
  1642. .PP
  1643. would make \fBperson\fR contain 
  1644. .IP
  1645.     {{ID 106} {NAME {Frank Zappa}} {JOB {musician and composer}}
  1646. .PP
  1647. Fields may contain subfields; `.' is the seperator character.  Subfields
  1648. are actually fields where the value is another keyed list.  Thus 
  1649. the following list has the top level fields \fIID\fR and \fINAME\fR, and
  1650. subfields \fINAME.FIRST\fR and  \fINAME.LAST\fR:
  1651. .IP
  1652.     {ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}
  1653. .PP
  1654. There is no limit to the recursive depth of subfields, allowing one
  1655. to build complex data structures.
  1656. .PP
  1657. Keyed lists are constructed and accessed via a number of commands.
  1658. All keyed list management commands take the name of the variable containing
  1659. the keyed list
  1660. as an argument (i.e. passed by reference), rather than passing the
  1661. list directly.
  1662. '@endhelp
  1663. '
  1664. '@help: tcl/keyedlists/keyldel
  1665. '@brief: Delete a field of a keyed list.
  1666. .TP
  1667. .B keyldel \fIlistvar\fR \fIkey\fR
  1668. .br
  1669. Delete the field specified by \fIkey\fR from the keyed list in the
  1670. variable \fIlistvar\fR.  This removes both the key and the value from
  1671. the keyed list.
  1672. '@endhelp
  1673. '
  1674. '@help: tcl/keyedlists/keylget
  1675. '@brief: Get the value of a field of a keyed list.
  1676. .TP
  1677. .B keylget \fIlistvar\fR ?\fIkey\fR? ?\fIretvar\fR | {}?
  1678. .br
  1679. Return the value associated with \fIkey\fR from the keyed list in the
  1680. variable \fIlistvar\fR.  If \fIretvar\fR is not specified, then the value will
  1681. be returned as the result of the command.  
  1682. In this case, if \fIkey\fR is not found in the
  1683. list, an error will result.
  1684. .sp
  1685. If \fIretvar\fR is specified and \fIkey\fR is in
  1686. the list, then the value is returned in the variable \fIretvar\fR and the
  1687. command returns \fB1\fR if the key was present within the list.
  1688. If \fIkey\fR isn't in the list, the command will return \fB0\fR,
  1689. and \fIretvar\fR will be left unchanged.  If \fB{}\fR is specified for
  1690. \fIretvar\fR, the value is not returned, allowing the Tcl programmer
  1691. to determine if a key is present in a keyed list without setting a
  1692. variable as a side-effect.
  1693. .sp
  1694. If \fIkey\fR is omitted, then a list of all the keys in
  1695. the keyed list is returned.
  1696. '@endhelp
  1697. '
  1698. '@help: tcl/keyedlists/keylkeys
  1699. '@brief: Get the keys in a keyed list.
  1700. .TP
  1701. .B keylkeys \fIlistvar\fR ?\fIkey\fR?
  1702. .br
  1703. Return the a list of the keyes in the keyed list in the
  1704. variable \fIlistvar\fR.  If \fIkeys\fR is specified, then it is the
  1705. name of a key field  who's subfield keys are to be retrieve.
  1706. '@endhelp
  1707. '
  1708. '@help: tcl/keyedlists/keylset
  1709. '@brief: Set the value of a field of a keyed list.
  1710. .TP
  1711. \fBkeylset\fR \fIlistvar\fR \fIkey\fR \fIvalue\fR ?\fIkey2\fR \fIvalue2\fR ...?
  1712. .br
  1713. Set the value associated with \fIkey\fR, in the keyed list contained in the
  1714. variable \fIlistvar\fR, to \fIvalue\fR.
  1715. If \fRlistvar\fR does not exists, it is created.  If \fIkey\fR
  1716. is not currently in the list, it will be added.  If it already exists, 
  1717. \fIvalue\fR replaces the existing value.  Multiple keywords and values may
  1718. be specified, if desired.
  1719. '@endhelp
  1720. '
  1721. .SH "STRING AND CHARACTER MANIPULATION COMMANDS"
  1722. .PP
  1723. The commands provide additional functionality to classify characters, convert
  1724. characters between character and numeric values, index into a string,
  1725. determine the length of a string, extract a range of character from a string,
  1726. replicate a string a number of times, and transliterate a string (similar to
  1727. the Unix \fItr\fR program).
  1728. '
  1729. '@help: tcl/strings/cindex
  1730. '@brief: Return indexed character from string.
  1731. .TP
  1732. .B cindex \fIstring indexExpr\fR
  1733. .br
  1734. Returns the character indexed by the expression \fIindexExpr\fR (zero based)
  1735. from \fIstring\fR.
  1736. .sp
  1737. If the expression \fIindexExpr\fR starts with the string \fBend\fR, then
  1738. \fBend\fR is replaced with the index of the last character in the string.  If
  1739. the expression starts with \fBlen\fR, then \fBlen\fR is replaced with the
  1740. length of the string.
  1741. '@endhelp
  1742. '@help: tcl/strings/clength
  1743. '@brief: Return length of specified string.
  1744. .TP
  1745. .B clength \fIstring\fR
  1746. .br
  1747. Returns the length of \fIstring\fR in characters.  
  1748. This command is a shortcut for:
  1749. .sp
  1750. .nf
  1751. .ft CW
  1752.     \fBstring length\fR \fIstring\fR
  1753. .ft R
  1754. .fi
  1755. '@endhelp
  1756. '
  1757. '@help: tcl/strings/crange
  1758. '@brief: Return range of characters from string.
  1759. .TP
  1760. .B crange \fIstring firstExpr lastExpr\fR
  1761. .br
  1762. Returns a range of characters from \fIstring\fR starting at the character
  1763. indexed by the expression \fIfirstExpr\fR (zero-based) until the character
  1764. indexed by the expression \fIlastExpr\fR.
  1765. .sp
  1766. If the expression \fIfirstExpr\fR or \fBlastExpr\fR starts with the string
  1767. \fBend\fR, then \fBend\fR is replaced with the index of the last character in
  1768. the string.  If the expression starts with \fBlen\fR, then \fBlen\fR is
  1769. replaced with the length of the string.
  1770. '@endhelp
  1771. '
  1772. '@help: tcl/strings/csubstr
  1773. '@brief: Return a substring from within a string.
  1774. .TP
  1775. .B csubstr \fIstring firstExpr lengthExpr\fR
  1776. .br
  1777. Returns a range of characters from \fIstring\fR starting at the character
  1778. indexed by the expression \fIfirstExpr\fR (zero-based) for \fIlengthExpr\fR
  1779. characters.  
  1780. .sp
  1781. If the expression \fIfirstExpr\fR or \fBlengthExpr\fR starts with the string
  1782. \fBend\fR, then \fBend\fR is replaced with the index of the last character in
  1783. the string.  If the expression starts with \fBlen\fR, then \fBlen\fR is
  1784. replaced with the length of the string.
  1785. '@endhelp
  1786. '
  1787. '@help: tcl/strings/ctoken
  1788. '@brief: Parse a token from a character string.
  1789. .TP
  1790. .B ctoken \fIstrvar separators\fR
  1791. .br
  1792. Parse a token out of a character string.
  1793. The string to parse is contained in the variable named \fIstrvar\fR.
  1794. The string \fIseparators\fR contains all of the valid separator characters
  1795. for tokens in the string.
  1796. All leading separators are skipped and the first token is returned.
  1797. The variable \fIstrvar\fR will be modified to contain the remainder of
  1798. the string following the token.
  1799. '@endhelp
  1800. '
  1801. '@help: tcl/strings/ctype
  1802. '@brief: Determine if a string has various characteristics.
  1803. .TP
  1804. .B ctype \fIclass string\fR 
  1805. .br
  1806. \fBctype\fR
  1807. determines whether all characters in \fIstring\fR are of the specified
  1808. \fIclass\fR.  It returns \fB1\fR if they are all of \fIclass\fR,
  1809. and \fB0\fR if
  1810. they are not, or if the string is empty.  This command also provides another
  1811. method (besides \fBformat\fR and \fBscan\fR) of converting between an ASCII
  1812. character and its numeric value.  The following \fBctype\fR commands are
  1813. available:
  1814. .RS 5
  1815. .TP
  1816. .B ctype alnum \fIstring\fR
  1817. Tests that all characters are alphabetic or numeric characters as defined by
  1818. the character set.
  1819. .TP
  1820. .B ctype alpha \fIstring\fR
  1821. Tests that all characters are alphabetic characters as defined by the
  1822. character set.
  1823. .TP
  1824. .B ctype ascii \fIstring\fR
  1825. Tests that all characters are an ASCII character (a non-negative number less
  1826. than 0200).
  1827. .TP
  1828. .B ctype char \fInumber\fR
  1829. Converts the numeric value, \fIstring\fR, to an ASCII character.  Number must
  1830. be in the range 0 through 255.
  1831. .TP
  1832. .B ctype cntrl \fIstring\fR
  1833. Tests that all characters are ``control characters'' as defined by the
  1834. character set.
  1835. .TP
  1836. .B ctype digit \fIstring\fR
  1837. Tests that all characters are valid decimal digits, i.e. 0 through 9.
  1838. .TP
  1839. .B ctype graph \fIstring\fR
  1840. Tests that all characters within are any character for which \fIctype print\fR
  1841. is true, except for space characters.
  1842. .TP
  1843. .B ctype lower \fIstring\fR
  1844. Tests that all characters are lowercase letters as defined by the character
  1845. set.
  1846. .TP
  1847. .B ctype ord \fIcharacter\fR
  1848. Convert a character into its decimal numeric value.  The string must be one
  1849. character long.
  1850. .TP
  1851. .B ctype space \fIstring\fR
  1852. Tests that all characters are either a space, horizontal-tab, carriage
  1853. return, newline, vertical-tab, or form-feed.
  1854. .TP
  1855. .B ctype print \fIstring\fR
  1856. Tests that all characters are a space or any character for which \fIctype
  1857. alnum\fR or \fIctype punct\fR is true or other ``printing character'' as
  1858. defined by the character set.
  1859. .TP
  1860. .B ctype punct \fIstring\fR
  1861. Tests that all characters are made up of any of the characters
  1862. other than the ones for which
  1863. \fBalnum\fR, \fBcntrl\fR, or \fBspace\fR is true.
  1864. .TP
  1865. .B ctype upper \fIstring\fR
  1866. Tests that all characters are uppercase letters as defined by the character
  1867. set.
  1868. .TP
  1869. .B ctype xdigit \fIstring\fR
  1870. Tests that all characters are valid hexadecimal digits, that is \fI0\fR
  1871. through \fI9\fR, a through \fIf\fR or \fIA\fR through \fIF\fR.
  1872. .RE
  1873. '@endhelp
  1874. '
  1875. '@help: tcl/strings/replicate
  1876. '@brief: Replicate string a number of times.
  1877. .TP
  1878. .B replicate \fIstring countExpr\fR
  1879. .br
  1880. Returns \fIstring\fR, replicated the number of times indicated by the
  1881. expression \fIcountExpr\fR.
  1882. '@endhelp
  1883. '
  1884. '@help: tcl/strings/translit
  1885. '@brief: Translate characters in a string according to patterns.
  1886. .TP
  1887. .B translit \fIinrange outrange string\fR
  1888. .br
  1889. Translate characters in \fIstring\fR, changing characters
  1890. occuring
  1891. in \fIinrange\fR
  1892. to the corresponding character in \fIoutrange\fR. \fIInrange\fR and 
  1893. \fIoutrange\fR may be list of characters or a range in the form `A-M'.
  1894. For example:
  1895. .nf
  1896. .ft CW
  1897.         translit a-z A-Z foobar
  1898. .ft R
  1899. .if
  1900. returns "FOOBAR".
  1901. '@endhelp
  1902. '
  1903. .SH "XPG/3 MESSAGE CATALOG COMMANDS"
  1904. .PP
  1905. These commands provide a Tcl interface to message catalogs that are compliant
  1906. with the X/Open Portability Guide, Version 3 (XPG/3).
  1907. .sp
  1908. Tcl programmers can use message catalogs to create applications that
  1909. are language-independent.  Through the use of message catalogs, prompts,
  1910. messages, menus and so forth can exist for any number of languages,
  1911. and they can altered, and new languages added,  without affecting any Tcl or C
  1912. source code, greatly easing the maintenance difficulties incurred by
  1913. supporting multiple languages.
  1914. .sp
  1915. A default text message is passed to the command that fetches entries
  1916. from message catalogs.
  1917. This allows the Tcl programmer to create message catalogs containing
  1918. messages in various languages, but still have a set of default messages
  1919. available
  1920. regardless of the presence of any message catalogs, and allow the programs
  1921. to press on without difficulty when no catalogs are present.
  1922. .sp
  1923. Thus, the normal
  1924. approach to using message catalogs is to ignore errors on \fBcatopen\fR, in
  1925. which case
  1926. \fBcatgets\fR will return the default message that was specified in the call.
  1927. .sp
  1928. The Tcl message catalog commands normally ignore most errors.  If it is
  1929. desirable to detect errors,
  1930. a special option is provided.  This is normally used only 
  1931. during debugging, to
  1932. insure that message catalogs are being used.  If your Unix implementation does
  1933. not have XPG/3 message catalog support, stubs will be compiled in that will
  1934. create a version of \fBcatgets\fR that always returns the default string.
  1935. This allows for easy
  1936. porting of software to environments that don't have support for
  1937. message catalogs.
  1938. .sp
  1939. Message catalogs are global to the process, an application with multiple
  1940. Tcl interpreters within the same process may pass and share message catalog
  1941. handles.
  1942. '
  1943. '@help: tcl/internation/catopen
  1944. '@brief: Open a message catalog.
  1945. .TP
  1946. .B catopen\fR ?\fB-fail\fR|\fB-nofail\fR? \fIcatname\fR
  1947. .br
  1948. Open the message catalog \fIcatname\fR.  This may be a relative path name,
  1949. in which case the \fBNLSPATH\fR environment variable is searched to find an
  1950. absolute path to the message catalog.  A handle in the form \fBmsgcat\fIN\fR
  1951. is returned.  Normally, errors are ignored, and in the case of a failed
  1952. call to \fBcatopen\fR, a handle is returned to an
  1953. unopened message catalog.  (This handle may still be passed to \fBcatgets\fR
  1954. and \fBcatclose\fR, causing \fBcatgets\fR to simply return the default string,
  1955. as described above.  If the \fB-fail\fR 
  1956. option is specified, an error is returned
  1957. if the open fails.  The option \fB-nofail\fR specifies the default behavior
  1958. of not returning an error when \fBcatopen\fR fails to open a specified
  1959. message catalog.
  1960. '@endhelp
  1961. '
  1962. '@help: tcl/internation/catgets
  1963. '@brief: Retrieve a message from a message catalog.
  1964. .TP
  1965. .B catgets \fIcatHandle setnum msgnum defaultstr\fR
  1966. .br
  1967. Retrieve a message form a message catalog. \fICatHandle\fR should be a
  1968. Tcl message catalog handle that
  1969. was returned by \fBcatopen\fR.  \fISetnum\fR is the message set number,
  1970. and \fImsgnum\fR is the message number. If the message catalog was not opened,
  1971. or the message set or message number cannot be found, then the default
  1972. string, \fIdefaultstr\fR, is returned.
  1973. '@endhelp
  1974. '
  1975. '@help: tcl/internation/catclose
  1976. '@brief: Close a message catalog.
  1977. .TP
  1978. .B catclose\fR ?\fB-fail\fR|\fB-nofail\fR? \fIcathandle\fR
  1979. .br
  1980. Close the message catalog specified by \fIcathandle\fR.
  1981. Normally, errors are ignored.  If \fB-fail\fR is
  1982. specified, any errors closing the message catalog
  1983. file are returned.  The option \fB-nofail\fR
  1984. specifies the default behavior of not returning an error.  The use of
  1985. \fB-fail\fR only makes sense if it was also
  1986. specified in the call to \fBcatopen\fR.
  1987. '@endhelp
  1988. '
  1989. .SH "TCL SHELL AND DEVELOPMENT ENVIRONMENT"
  1990. .sp
  1991. '@help: tcl/tclshell/intro
  1992. '@brief: Introduction to the tcl shell.
  1993. .B tcl ?-qn? ?-f? \fIscript\fB?|?-c \fIcommand\fB? ?\fIargs\fR?
  1994. .PP
  1995. \fBTcl\fR starts the interactive Tcl command interpreter.  The Tcl shell
  1996. provides an environment for writing, debugging and executing Tcl scripts.  The
  1997. functionality of the Tcl shell can be easily obtained by any application
  1998. that includes Tcl.
  1999. .PP
  2000. The \fBtcl\fR command, issued without any arguments,
  2001. invokes an interactive Tcl shell, allowing the user to interact
  2002. directly with Tcl, executing any Tcl commands at will and viewing
  2003. their results.
  2004. .PP
  2005. If \fIscript\fR is specified, then the script is executed non-interactively
  2006. with any additional arguments, \fIargs\fR, being supplied in the
  2007. global Tcl
  2008. variable `\fBargv\fR'.  If 
  2009. \fIcommand\fR is supplied, then this command (or semicolon-separated
  2010. series of commands) is executed, with `\fBargv\fR' containing
  2011. any \fIargs\fR.
  2012. .PP
  2013. The Tcl shell is intended as an environment for Tcl program development and
  2014. execution.  While it is not a full-featured interactive shell, it provides a
  2015. comfortable environment for the interactive development of Tcl code.  Note
  2016. that the package library code described here overrides the \fBunknown\fR
  2017. command provided as part of the standard Berkeley Tcl library facility,
  2018. although Tcl source libraries coded to that standard can be loaded and used by
  2019. Extended Tcl.
  2020. .PP
  2021. The following command line flags are recognized by the Tcl shell command
  2022. line parser:
  2023. .TP
  2024. .B \-q
  2025. Quick initialization flag.  The Tcl initiaization file is not evaluated
  2026. and the \fBauto_path\fR variable is not set.  Tcl auto-load libraries will
  2027. not be available.
  2028. .TP
  2029. .B \-n
  2030. No procedure call stack dump.  The procedure call stack will not be displayed
  2031. when an error occurs, only the error message.  Useful in the #! line of
  2032. already debugged scripts.
  2033. .TP
  2034. .B \-f
  2035. Takes the next argument as a script for Tcl to source, rather than entering
  2036. interactive
  2037. mode.  The \fB-f\fR flag is optional.  Normally the first argument that does
  2038. not start with a `-' is taken as the script to execute unless the `-c' option
  2039. is specified.  Any following arguments are passed to the script
  2040. via \fBargv\fR,
  2041. thus any other Tcl shell command-line flags must precede this option.
  2042. .TP
  2043. .B \-c
  2044. Take the next argument as a Tcl command to execute.  It may contain series of 
  2045. commands to execute, separated by `;'.  Any following arguments are passed in
  2046. \fBargv\fR, thus, as with \fB-f\fR, any other Tcl shell flags must precede
  2047. this option.
  2048. .TP
  2049. .B \-\-
  2050. Mark the end of the arguments to the Tcl shell. All arguments following this
  2051. are passed in the Tcl variable \fBargv\fR.  This is useful to pass arguments
  2052. without attempting to execute a Tcl script.
  2053. .PP
  2054. The result string returned by a command executed from the Tcl shell command
  2055. line is
  2056. normally echoed back to the user.  If an error occurs, then the string result
  2057. is displayed, along with the error message.  The error message will be
  2058. preceded by the string ``Error:''.
  2059. .PP
  2060. The \fBset\fR command is a special case.  If the command is called to set
  2061. a variable (i.e. with two arguments), then the result will not be echoed.
  2062. If only one argument, the name of a variable, is supplied to \fBset\fR, then
  2063. the result will be echoed.
  2064. .PP
  2065. If an unknown Tcl command is entered from the command line, then the Unix
  2066. command path, specified in the environment variable \fBPATH\fR,
  2067. will be searched for a command of the same name.
  2068. If the command is found, it will be executed with any arguments remaining
  2069. on the Tcl command line being passed as arguments to the command.
  2070. This feature is provided to enhance the interactive environment for developing
  2071. Tcl scripts.
  2072. .PP
  2073. Automatic execution of programs in this manner is only supported from the
  2074. command line, not in script files
  2075. or in procedures, to reduce confusion and mistakes while programming
  2076. in Tcl.  Scripts should use the Tcl \fBexec\fR or \fBsystem\fR 
  2077. commands to run Unix commands.
  2078. '@endhelp
  2079. '
  2080. .SH "HELP FACILITY"
  2081. '@help: help
  2082. '@brief: Tcl help facility.
  2083. .PP
  2084. The help facility allows one to look up help pages which where extracted
  2085. from the standard Tcl manual pages and Tcl scripts during Tcl
  2086. installation.  Help files are structured as a multilevel tree of
  2087. subjects and help pages.  Help files are found by searching directories
  2088. named \fBhelp\fR in the directories listed in the \fBauto_path\fR
  2089. variable.  All of the files in the list of help directories form a
  2090. virtual root of the help tree.  This method allows multiple applications
  2091. to provide help trees without having the files reside in the same
  2092. directory.  The following commands and options are provided with the
  2093. help package:
  2094. .TP
  2095. .B help
  2096. .br
  2097. Help, without arguments, lists of all the help subjects and pages under
  2098. the current help subject.
  2099. .TP
  2100. .B help \fIsubject\fR
  2101. Displays all of help pages and lower level subjects (if any exist) under
  2102. the subject \fIsubject\fR.
  2103. .TP
  2104. .B help \fIsubject/helppage\fR
  2105. Display the specified help page.  The help output is passed through a simple
  2106. pager if output exceeds 23 lines, pausing waiting for a return to be entered.
  2107. If any other character is entered, the output is terminated.
  2108. .TP
  2109. .B helpcd ?\fIsubject\fR?
  2110. Change the current subject, which is much like the Unix current
  2111. directory.  If
  2112. \fIsubject\fR is not specified, return to the top-level of the help tree.
  2113. Help subject path names may also include ``..'' elements.
  2114. .TP
  2115. .B helppwd
  2116. Displays the current help subject.
  2117. .TP
  2118. .B help help | ?
  2119. Displays help on the help facility at any directory level.
  2120. .TP
  2121. .B apropos \fIpattern\fR
  2122. This command locates subjects by searching their one-line descriptions for a
  2123. pattern.  \fRApropos\fR is useful when you can remember part of the name or
  2124. description of a command, and want to search through the one-line summaries
  2125. for matching lines.  Full regular expressions may be specified (see 
  2126. the \fBregexp\fR command).
  2127. '@endhelp
  2128. '
  2129. .SH "TCL SHELL INITIALIZATION SEQUENCE"
  2130. '@help: tcl/tclshell/initialize
  2131. '@brief: Tcl shell initialization.
  2132. .PP
  2133. When Extended Tcl is installed, the standard runtime files are places in the
  2134. Tcl master directory, which is configured when Tcl is built.  This master
  2135. directory normally contains the Tcl initialization file (TclInit.tcl), the
  2136. standard Tcl library files (tcl.tlib, tk.tlib) and the help files.
  2137. The Tcl master directory is named after the version of Tcl it is associated
  2138. with, e.g. \fB/usr/local/tclX7.0a\fR.  The path to the Tcl master directory
  2139. is available from the \fBinfo library\fR command.
  2140. .PP
  2141. The first step in initializing the Tcl shell is to locate the Tcl
  2142. initialization file, normally \fBTclInit.tcl\fR.  If an environment variable
  2143. \fBTCLINIT\fR exists, it contains the path to the Tcl initialization file.
  2144. If the \fBTCLINIT\fR environment variable is not set, the file
  2145. \fBTclInit.tcl\fR is used from the default Tcl master directory.
  2146. .PP
  2147. \fBTcl\fR then evaulates the Tcl initialization file.  The \fBauto_path\fR
  2148. variable is initialized to the Tcl master directory and may be augmented by
  2149. the intialization file or the application.
  2150. Other procedures and variables used by the Extended Tcl shell are also defined
  2151. by this file.
  2152. .PP
  2153. If the Tcl is invoked interactively, it will source a file
  2154. named \fI.tclrc\fR in the
  2155. user's home directory, if it exists.  Tcl is viewed primarily as a programming
  2156. language, not an interactive shell, so the \fI.tclrc\fR is intended for use for
  2157. loading development utilities, not to support applications,
  2158. which should not have
  2159. to rely
  2160. on the user's environment in such a manner.
  2161. .PP
  2162. Some applications, such as \fBwishx\fR, have additional initialization files.
  2163. They may have environment variables that override the default location
  2164. of thise initialization files.
  2165. Tcl global variable \fBauto_path\fR will contain the directories contain those
  2166. initialization files.
  2167. '@endhelp
  2168. '
  2169. .SH "TCL SHELL VARIABLES"
  2170. '@help: tcl/tclshell/variables
  2171. '@brief: Tcl shell variables.
  2172. ???Do something with this section???
  2173. .PP
  2174. The following variables are set and/or used by the Tcl shell.
  2175. .TP
  2176. .TP
  2177. .B argv0
  2178. Contains the name of the Tcl program specified on the command line or
  2179. the name that the Tcl shell was invoked under if no program was specified.
  2180. .B argc
  2181. Contains a count of the number of \fIargv\fR arguments (0 if none).
  2182. .B argv
  2183. A list containing the arguments passed in from the command line, excluding
  2184. arguments used by the Tcl shell.  The first element is the first passed
  2185. argument, not the program name.
  2186. .TP
  2187. .B tcl_interactive
  2188. Set to \fB1\fR if Tcl shell is invoked interactively, or \fB0\fR if the
  2189. Tcl shell is directly executing a script.  Normally checked by scripts so
  2190. that they can function as a standalone application if specified on the
  2191. command line, but merely load in and not execute if loaded during an
  2192. interactive invocation of Tcl.
  2193. .TP
  2194. .B auto_path
  2195. Path to search to locate Tcl scripts.  Used by the 
  2196. \fBauto_load\fR command and the TclX unknown command handler.
  2197. The path is a Tcl list of directory names.
  2198. .TP
  2199. .B tcl_prompt1
  2200. Contains code to run to generate the prompt used when interactively prompting
  2201. for commands.  The code in this hook will be evaluated and the result will be
  2202. used for the prompt.
  2203. .TP
  2204. .B tcl_prompt2
  2205. Contains code to run to generate the prompt used when interactively prompting
  2206. for continuation of an incomplete command.  The code in this hook
  2207. will be evaluated and the result will be used for the prompt
  2208. .TP
  2209. .B TCLENV
  2210. Array that contains information used internally by various Tcl procedures that
  2211. are part of the Tcl shell..  Don't change this array or strange errors might
  2212. result.
  2213. '@endhelp
  2214. '
  2215. .SH "TCL SHELL PROCEDURES"
  2216. .PP
  2217. The follow additional procedures are defined by the Tcl shell and may be 
  2218. generally useful:
  2219. .TP
  2220. '@help: tcl/libraries/auto_load_file
  2221. '@brief: Search the auto_path for a file to source.
  2222. .B auto_load_file \fIfile\fR
  2223. .br
  2224. Source a file, as with the \fBsource\fR command, except search
  2225. \fBauto_path\fR for the file.
  2226. '@endhelp
  2227. '
  2228. .TP
  2229. '@help: tcl/libraries/searchpath
  2230. '@brief: Search a path list for a file.
  2231. .B searchpath \fIpath file\fR
  2232. .br
  2233. Search all directories in the specified path, which is a Tcl list, for the
  2234. specified file.  Returns the full path name of the file, or an empty string
  2235. if the requested file could not be found.
  2236. '@endhelp
  2237. '
  2238. '@help: tcl/libraries/packagelib
  2239. '@brief: Tcl loadable libraries and packages.
  2240. .SH "TCL LOADABLE LIBRARIES AND PACKAGES"
  2241. .PP
  2242. Extended Tcl supports standard Tcl \fBtclIndex\fR libraries and package
  2243. libraries. A package library file can contain multiple independent Tcl
  2244. packages.  A package is a named collection of related Tcl procedures and
  2245. initialization code.
  2246. .PP
  2247. The package library file is just a regular Unix text file, editable with
  2248. your favorite text editor, containing packages of Tcl source code. The
  2249. package library file name must have the suffix \fB.tlib\fR.  An index
  2250. file with the suffix \fB.tndx\fR, corresponding to the package library.
  2251. The \fB.tndx\fR will be automatically created by Tcl whenever it is out
  2252. of date or missing (provided there is write access to the directory.
  2253. .PP
  2254. The variable \fBauto_path\fR contains a list of directories that are
  2255. searched for libraries.  The first time an unknown command trap is take,
  2256. the indexes for the libraries are loaded into memory. If the
  2257. \fBauto_path\fR variable is changed during execution of a program, it
  2258. will be re-searched. Only the first package of a given name found during
  2259. the execution of a program is loaded.  This can be overridden with
  2260. \fBloadlibindex\fR command.
  2261. .PP
  2262. The start of a package is delimited by:
  2263. .IP
  2264. .B #@package: \fIpackage_name proc1\fR ?\fI..procN\fR?
  2265. .PP
  2266. These lines must start in column one.  Everything between the
  2267. \fB#@package:\fR keyword and the next \fB#@package:\fR keyword or a
  2268. \fB#@packend\fR keyword, or the end of the file, becomes part of the
  2269. named package.
  2270. The specified procedures, \fIproc1..procN\fR, are the entry points of
  2271. the package.  When a command named in a package specification is
  2272. executed and detected as an unknown command, all code in the specified
  2273. package will be sourced.
  2274. This package should define all of the procedures named on the package
  2275. line, define any support procedures required by the package and do any
  2276. package-specific initialization.  Packages declarations maybe continued
  2277. on subsequent lines using standard Tcl backslash line continuations.
  2278. The \fB#@packend\fR keyword is useful to make sure only the minimum
  2279. required section of code is sourced.  Thus for example a large comment
  2280. block at the beginning of the next file won't be loaded.
  2281. .PP
  2282. Care should be taken in defining \fIpackage_name\fR, as the first package
  2283. found in the path by with a given name is loaded.  This can be useful in
  2284. developing new version of packages installed on the system.
  2285. .PP
  2286. For example, in a package source file, the presence of the following line:
  2287. .IP
  2288. \fB#@package: directory_stack pushd popd dirs\fR
  2289. .PP
  2290. says that the text lines following that line in the package file up
  2291. to the next \fIpackage\fR line or the end of the file is a package named
  2292. \fBdirectory_stack\fR and that an attempt to execute either \fIpushd\fR,
  2293. \fIpopd\fR or \fIdirs\fR when the routine is not already defined will cause 
  2294. the \fBdirectory_stack\fR portion of the package file to be loaded.
  2295. '@endhelp
  2296. '
  2297. .SS "PACKAGE LIBRARY MANAGEMENT COMMANDS"
  2298. .PP
  2299. Several commands are available for building and managing package
  2300. libraries.  Commands that are extended versions of the standard
  2301. Tcl library commands are listed here.  All of the standard Tcl library
  2302. management commands and variables are also supported.
  2303. '
  2304. .TP
  2305. '@help: tcl/libraries/auto_commands
  2306. '@brief: List names of loadable library commands and procedures.
  2307. .B auto_commands\fR ?\fB-loaders\fR?
  2308. Lists the names of all known loadable procedures and commands
  2309. procedures.  If \fB-loaders\fR is specified, the command that will be
  2310. executed to load the command will also be returned.
  2311. '@endhelp
  2312. '
  2313. .TP
  2314. '@help: tcl/libraries/buildpackageindex
  2315. '@brief: Build an index to a package library.
  2316. .B buildpackageindex \fIlibfile\fR
  2317. .br
  2318. Build an index for a package library.  The the \fIlibfile\fR name must end with
  2319. the suffix \fB.tlib\fR.
  2320. '@endhelp
  2321. '
  2322. .TP
  2323. '@help: tcl/libraries/convert_lib
  2324. '@brief: Convert an Ousterhout style tclIndex file to a package library.
  2325. .B convert_lib \fItclIndex packagelib ?ignore?\fR
  2326. .br
  2327. Convert a Ousterhout style \fItclIndex\fR index file and associate source
  2328. files into a package library \fBpackagelib\fR.  If \fBpackagelib\fR does not
  2329. have a \fB.tlib\fR extension, one will be added.  Any files specified in 
  2330. \fItclIndex\fR that are in the list \fIignore\fR will be skipped.  Files
  2331. listed in \fIignore\fR should just be the base file names, not full paths.
  2332. '@endhelp
  2333. '
  2334. .TP
  2335. '@help: tcl/libraries/auto_load
  2336. '@brief: Force an autoload of a command.
  2337. .B auto_load \fI?command?\fR
  2338. .br
  2339. Attempt to load the specified \fIcommand\fR from a loadable library.
  2340. loading the package containing the procedure.  If the package indexes
  2341. have not been loaded for all package libraries in \fBauto_path\fR, they
  2342. will be loaded.  Out-of-date library indexes will be rebuilt if they are
  2343. writable.  The procedure returns \fB1\fR if the command was sucessfully
  2344. loaded, or \fB0\fR if it was not.
  2345. .PP
  2346. Duplicated package names are skipped, the first package of a given name
  2347. found in the path is loaded.  If the \fBauto_path\fR has changed since
  2348. the last load, indexes will be reloaded (duplicate packages will not be
  2349. redefined).
  2350. .PP
  2351. If \fIcommand\fR is not specified, the indexes will be loaded, if they
  2352. have not alreay been loaded or if the \fBauto_pathfR variable has
  2353. changed, but no command will be loaded.
  2354. '@endhelp
  2355. '
  2356. .TP
  2357. '@help: tcl/libraries/loadlibindex
  2358. '@brief: Load the index of a package library
  2359. .B loadlibindex \fIlibfile.tlib\fR
  2360. .br
  2361. Load the package library index of the library file \fBlibfile\fR (which
  2362. must have the suffix \fI.tlib\fR).  Package library indexes along the
  2363. \fauto_path\fR are loaded automatically on the first \fBdemand_load\fR;
  2364. this command is provided to explicitly load libraries that are not in
  2365. the path.  If the index file (with a \fI.tndx\fR suffix) does not exists
  2366. or is out of date, it will be rebuilt if the user has directory
  2367. permissions to create it. If a package with the same name as a package
  2368. in \fIlibfile.tlib\fR has already been loaded, its definition will be
  2369. overridden by the new package.  However, if any procedure has actually
  2370. been used from the previously defined package, the procedures from
  2371. \fIlibfile.tlib\fR will not be loaded.
  2372. .PP
  2373. This command will also load an index built by \fBmkindex.tcl\fR program
  2374. supplied with standard Tcl.  This file must be named "\fBtclIndex\fR".
  2375. '@endhelp
  2376. '
  2377. .TP
  2378. '@help: tcl/libraries/auto_packages
  2379. '@brief: List all packages.
  2380. .B auto_packages ?\fI-location\fR?
  2381. .br
  2382. Returns a list of the names of all defined packages. If \fI-location\fR
  2383. is specified, a list of pairs of package name and the \fB.tlib\fR path
  2384. name, offset and length of the package within the library.
  2385. '@endhelp
  2386. '
  2387. .TP
  2388.